跳到主要内容

MCP Guide

The Daspire MCP Gateway lets AI assistants inspect connector specs, prepare pipeline and Reverse ETL changes, run syncs, and review approvals through the Daspire Control API.

Example local configuration:

{
  "mcpServers": {
    "daspire": {
      "command": "node",
      "args": ["/path/to/daspire-mcp/bin/daspire-mcp.js"],
      "env": {
        "DASPIRE_API_BASE_URL": "https://api.daspire.com/daspire/api/control/v1",
        "DASPIRE_TOKEN": "<user-session-token>"
      }
    }
  }
}

Tools​

  • daspire_list_workspaces

  • daspire_list_connectors

  • daspire_list_sources

  • daspire_update_source

  • daspire_set_odbc_sql_streams

  • daspire_rename_source

  • daspire_delete_source

  • daspire_list_pipelines

  • daspire_list_connections

  • daspire_delete_connection

  • daspire_get_connector_spec

    Qualified Clean MySQL destination specs may include read-only capability_binding (profile, connector_id, spec_version, source_hash, runtime_projection_hash). The tool preserves this binding and the schema capability annotations unchanged. They are not customer configuration fields. Preserve explicit false values; when a mode-specific check value is omitted, the runtime uses that mode's default. Do not infer that a legacy fallback spec has the same qualified capabilities.

  • daspire_get_source_oauth_consent_url

  • daspire_complete_source_oauth

  • daspire_prepare_pipeline

  • daspire_apply_pipeline

  • daspire_pause_pipeline

  • daspire_resume_pipeline

  • daspire_list_reverse_etl_models

  • daspire_apply_reverse_etl_model

  • daspire_delete_reverse_etl_model

  • daspire_list_reverse_etl_destinations

  • daspire_apply_reverse_etl_destination

  • daspire_delete_reverse_etl_destination

  • daspire_list_reverse_etl_activations

  • daspire_prepare_reverse_etl_activation

  • daspire_apply_reverse_etl_activation

  • daspire_delete_reverse_etl_activation

  • daspire_run_reverse_etl_activation

  • daspire_get_reverse_etl_run

  • daspire_run_sync

  • daspire_get_job

  • daspire_list_approvals

  • daspire_list_approval_policies

  • daspire_approve_change

  • daspire_reject_change

MCP write tools create approval proposals by default. Workspace administrators can turn approval on or off per MCP action category in Workspace Settings > Approval. Pass execution_mode: "proposal" when you explicitly want a proposal even for a category that allows direct execution.

Use daspire_rename_source for source display-name changes. The Control API preserves the existing source connectionConfiguration before applying the rename so a name-only patch does not clear connector configuration. For Amazon Ads regional rename work, include source_identifier to update connectionConfiguration.source_name at the same time:

{
  "source_id": "source_123",
  "name": "Ads CLEVAST Amazon EU",
  "source_identifier": "CLEVAST Amazon EU",
  "execution_mode": "proposal"
}

Delete connections before deleting their source. daspire_delete_source rejects sources that still have associated connections and returns a post-delete verification result after execution. Delete requests follow the workspace approval policy for the relevant MCP category.

Pipeline Creation​

Before preparing a MySQL destination, use daspire_get_connector_spec for its deployed schema and mode-specific capability metadata. Clean MySQL's concurrent_safe_check_default_enabled_by_mode distinguishes ordinary and legacy-raw MySQL (false) from explicitly admitted AnalyticDB (true); the scalar default describes only the default transactional mode. Leave omitted settings omitted, and preserve explicit customer values. A JSON Schema conditional default is not authorization to switch a connection's mode or to modify its configuration.

Clean MySQL does not implement SSH tunnels, arbitrary JDBC parameters, cross-database writes or normalization inside the writer. Do not infer these capabilities from old-engine setup fields or MySQL protocol compatibility. See the mode capability matrix. The generic spec MCP tool passes through the schema/metadata without adding defaults; no new MySQL-specific MCP write tool or automatic configuration migration is introduced.

Use daspire_prepare_pipeline to preview the normalized plan, then pass the same payload to daspire_apply_pipeline. Pipeline catalogs use the product-facing flat stream shape; the Control API converts each selected stream to the runtime stream and config catalog shape before execution. Product-facing schedule input is also normalized to the runtime scheduleData shape; callers should not send runtime legacy and new schedule schemas together.

{
  "payload": {
    "name": "Amazon BR inventory <> analytic_mysql",
    "source_id": "src_source_product_id",
    "destination_id": "dst_destination_product_id",
    "catalog": {
      "streams": [
        {
          "name": "GET_FBA_INVENTORY_PLANNING_DATA",
          "selected": true,
          "sync_mode": "full_refresh",
          "destination_sync_mode": "append",
          "cursor_field": ["sku"],
          "primary_key": [["sku"]]
        }
      ]
    },
    "schedule_type": "basic",
    "schedule": {
      "type": "basic",
      "interval_unit": "hours",
      "interval": 12
    },
    "status": "active"
  }
}

Use daspire_pause_pipeline and daspire_resume_pipeline for operational status changes. These tools accept pipeline_id, keep schedule/catalog/state unchanged, and do not start a sync job. Legacy runtime connection ids remain accepted during rollout, but product pipeline ids are preferred.

Connection inventory reads use the latest Native job for Native-owned pipelines, not the old legacy job history. executionStatusSource: native identifies this projection. latestSyncJobStatus: not_started with a null timestamp means no Native job exists; an enabled never-run connection displays incomplete, while configuredStatus preserves its configured status. A cancelled or failed job is not a successful recovery. Paused configuration remains paused. Status reads do not start jobs or modify historical results; unavailable Native status is reported as an error instead of falling back to old success. The web page's filters, pagination and health totals use the same projected results.

Connection Recent activity retains sync and reset history from before and following a move to Native execution. Its history API (POST /api/control/v1/jobs/list) returns jobs: [{job, attempts}] and totalJobCount; configId scopes the connection and pagination.pageSize / rowOffset paginate the combined history. A failed history refresh is an error, not an empty history. This does not change the latest Native status shown in connection inventory. The MCP gateway's existing job-detail tool is unchanged; this compatibility repair adds no tool.

Mailcoach email content​

After the Native Mailcoach content-update Control release, the Mailcoach 0.0.5+ image and its matching connector spec are qualified for the source, the existing daspire_update_source tool accepts the partial configuration {"campaign_content_mode":"omit"} for reporting without campaign email content. inline restores the previous payload shape; separate exposes an optional campaign_content stream that must be explicitly selected in the connection catalog. Source settings affect every connection using that source: check its consumers before updating it. Use execution_mode: proposal when preparing a reviewable change.

Native saves accept only campaign_content_mode in this partial patch. They validate every dependent connection before changing credentials or schedules. MAILCOACH_CONTENT_RUNTIME_NOT_READY means its qualified image or schema is not ready; MAILCOACH_CONTENT_CATALOG_CONFLICT means an archive stream is still selected when changing away from separate. Neither error saves the change.

These modes remain full refresh. They do not enable incremental reads, change append/overwrite semantics or remove stored historical data. Reconcile unresolved historical commits before changing a recovering source. An old scheduled image does not gain content filtering merely because the configuration saves. See the Mailcoach setup guide.

ODBC Custom SQL Streams​

Use daspire_set_odbc_sql_streams to switch an existing ODBC source into Custom SQL mode and replace its SQL stream definitions. The tool writes source_mode: "custom_sql" and sql_streams into the source configuration while preserving the rest of the source configuration through the Control API partial-update path.

Each stream requires a name and a read-only SELECT or WITH query. namespace is optional. cursor_field is optional and enables the SQL stream to be configured for incremental sync when the query returns that column. primary_key may be a single column string or an array of column strings; the MCP gateway normalizes it to the array format used by the ODBC connector.

{
  "source_id": "source_123",
  "streams": [
    {
      "name": "netsuite_may_transactions",
      "namespace": "NetSuite2",
      "query": "SELECT id, tranid, trandate FROM transaction WHERE trandate >= '2026-05-01' AND trandate < '2026-06-01'",
      "cursor_field": "trandate",
      "primary_key": "id"
    }
  ],
  "execution_mode": "proposal"
}

The gateway rejects empty stream lists, duplicate namespace.name keys, multi-statement SQL, and common write/DDL verbs before sending the proposal. The ODBC connector runtime still performs the final SQL validation when the source is discovered or synced.

Connector OAuth​

Use daspire_get_connector_spec first to inspect whether a source requires OAuth. For source connectors such as PayPal and QuickBooks, daspire_get_source_oauth_consent_url returns the provider authorization URL through the Daspire Control API. After the provider redirects back to Daspire, pass the callback payload to daspire_complete_source_oauth.

The completion tool returns a Daspire credential_handle; provider tokens are stored by Daspire and are not returned to the MCP client. Use that handle when creating or updating the source configuration.

The Amazon Ads form uses /api/control/v1/connectors/amazon-ads/profiles/preview to list profiles with the newly returned handle before saving. This form preview intentionally has no dedicated MCP tool: MCP source configuration continues through the existing OAuth and source update tools, without adding a tool that accepts inline provider secrets.

MCP only exposes OAuth flows that are available through the Daspire Control API. Legacy runtime OAuth endpoints are internal compatibility details and are not part of the public MCP surface.

Example consent request:

{
  "payload": {
    "workspaceId": "workspace_uuid",
    "connector_id": "conn_source_product_id",
    "redirectUrl": "https://app.daspire.com/auth_flow",
    "oAuthInputConfiguration": {}
  }
}

Example completion request:

{
  "payload": {
    "workspaceId": "workspace_uuid",
    "connector_id": "conn_source_product_id",
    "queryParams": {
      "code": "provider_code",
      "state": "provider_state"
    },
    "redirectUrl": "https://app.daspire.com/auth_flow"
  }
}

Example source credential reference after completion:

{
  "connector_id": "source_definition_uuid",
  "name": "PayPal transactions",
  "credential_handle": "cred_source_oauth_abc123",
  "configuration": {
    "start_date": "2026-01-01"
  }
}

Reverse ETL Configuration​

Reverse ETL configuration is split into three resources:

  • Models select a source table or view and define the fields, primary key, and optional cursor.
  • Destinations define the operational target such as http or clickup.
  • Activations connect a model to a destination, define field mappings, schedule behavior, and compile the underlying sync connection.

Create or update a model with daspire_apply_reverse_etl_model:

{
  "payload": {
    "name": "Warehouse customers",
    "source_id": "source_123",
    "stream_namespace": "analytics",
    "stream_name": "customers",
    "selected_fields": ["id", "email", "company"],
    "primary_key": "id",
    "cursor_field": "updated_at"
  }
}

Create or update a destination with daspire_apply_reverse_etl_destination. Do not send provider secrets through MCP; use Daspire secure credential entry or OAuth and reference the resulting credential_handle.

ClickUp supports OAuth and personal API token entry in the Daspire UI. Both return the same credential-handle contract for Reverse ETL. The write-only POST /api/control/v1/credentials/clickup/api-token endpoint is intentionally not an MCP tool, so provider tokens do not pass through model messages or tool history. Connect in the secure UI, then use its opaque handle in MCP destination operations.

{
  "payload": {
    "name": "ClickUp customer list",
    "type": "clickup",
    "credential_handle": "cred_123",
    "configuration": {
      "workspace_id": "901",
      "list_id": "456"
    }
  }
}

Create or update an activation with daspire_apply_reverse_etl_activation:

{
  "payload": {
    "name": "Customer updates to ClickUp",
    "model_id": "revmdl_123",
    "destination_id": "revdst_123",
    "external_key_field": "email",
    "field_mappings": {
      "name": "company",
      "email": "email"
    },
    "schedule_type": "manual",
    "status": "active"
  }
}

Include model_id, destination_id, or activation_id in the payload to update an existing resource. Use daspire_prepare_reverse_etl_activation to preview the compiled activation payload before creating an approval, daspire_run_reverse_etl_activation to trigger a manual run, and daspire_get_reverse_etl_run to inspect run status.

Native Qordo Activation​

Use daspire_list_native_activation_sources and daspire_probe_native_activation_source for native warehouse setup checks. After a database password is entered through Daspire's secure UI, daspire_create_native_activation_source can submit the opaque credential handle and non-secret host/database configuration for approval. The MCP tool never accepts a database password. Connect Qordo tokens in the Daspire UI; raw Qordo token creation/rotation is also intentionally not exposed through MCP. daspire_check_qordo_credential accepts only a handle, and daspire_discover_qordo_resources browses workspace resources.

Existing Reverse ETL model, destination, prepare and activation tools accept type: qordo and native field policies. The manual-run tool accepts command_id; reuse it after an ambiguous response. daspire_retry_activation_run requires a stable command ID and retries only unfinished records from the original run. It follows the existing manual-run approval policy. Use daspire_list_activation_runs, daspire_get_reverse_etl_run and daspire_list_activation_rows for durable results. not_ready is not an accepted job or successful sync.

Stripe re-authentication​

Use the existing source OAuth and source update tools. Stripe returns a connected credential handle only after account verification. In Native mode, apply the owned handle to the same account with unchanged name and replication settings. A scheduling reconciliation error requires support before retrying. No provider key is accepted or returned through this flow; the existing MCP surface is unchanged.

Hubstaff re-authentication​

Use the existing OAuth and source update tools with an owned credential handle; do not send provider tokens through MCP. Native source save verifies the original Hubstaff account and access to every original organization, then saves both OAuth tokens while preserving source name, replication settings, checkpoints, enabled/disabled state and cadence. It does not trigger a sync or refresh a token. A SOURCE_REAUTH_RECONCILE_REQUIRED or SOURCE_REAUTH_INTERRUPTED response requires operator reconciliation before retrying. Autonomous Native refresh-token rotation is a separate requirement, not established by this save. No new MCP tool or argument is introduced.

WorldFirst own-application credentials​

Enter application signing keys and tokens only through the secure Daspire source settings UI, not an MCP prompt. Choose the application's API region and supply the WorldFirst platform public key. Editing an existing Native source repairs credentials while keeping Client ID, region, account, name and replication settings unchanged; use a new source for another application/account. Saving is not a successful provider check or sync. Reconciliation errors require support before retrying. No raw-key MCP tool is added intentionally; Daspire-managed WorldFirst authorization remains unavailable until provider onboarding and the complete authorization flow are verified.