Skip to main content

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_create_source

  • daspire_check_source

  • daspire_discover_source

  • 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_discover_source first, then copy its exact catalogId (also exposed as catalog_id by some clients) as source_catalog_id and its exact stream names into daspire_prepare_pipeline. Pass the same payload to daspire_apply_pipeline; do not invent or singularize stream names. The server binds the receipt to the selected source, rejects streams absent from that discovery, and restores the authoritative discovered stream schema before execution. Pipeline catalogs accept the product-facing flat stream shape; the Control API keeps selected streams, consumes the top-level product selected hint, and emits the runtime config.selected=true catalog shape. 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",
    "source_catalog_id": "00000000-0000-0000-0000-000000000000",
    "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.

daspire_run_sync requires a stable command_id. Reuse that value only when reconciling an ambiguous response. An EXECUTION_CONFLICT means a sync/reset is already active or the registered schedule material changed; refresh pipeline/job status before deciding whether another command is appropriate.

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.

Freshness uses latestSyncJobUpdatedAt when available so a long-running job is not marked delayed merely because its creation time is old. Runtime scheduling is projected as nativeScheduleEnabled, nativeScheduleNextRunAt and nativeScheduleMode. If an active timed product connection has a disabled Native schedule, it is reported as incomplete with nativeScheduleState: disabled; the UI labels this condition Schedule disabled rather than Delayed. A successful product update reconciles the runtime schedule to the customer's saved active/manual/frequency settings. It does not manually start or replay a sync.

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. Response signature verification is the default and requires the WorldFirst platform public key. Explicitly selecting response_verification=private_key_only permits read-only statement queries without that key; HTTPS certificate validation remains enabled, but response digital signatures are not verified. A configured platform key always enables verification, and an existing verified source cannot be downgraded by an update. 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.

Feishu EHR employee roster​

For an EHR-enabled source, use the existing source configuration tools with modules: ["ehr"] and the connection catalog stream ehr_employees in full_refresh mode. Discover the current source catalog after configuration; do not copy Approval's default stream list. EHR requires an approved custom app and a tenant token with employee roster access. Source settings affect all connections using that source, so keep a dedicated HR source when the roster has a different access scope or reporting destination.

The existing source configuration and discovery APIs use the Native setup bridge; a separate MCP tool is not planned. Release-owned registry schema publication remains a host operator capability and is not exposed as a customer MCP tool. See the Feishu setup guide for snapshot semantics and downstream validation.

Source setup​

Use daspire_create_source with a connector ID, name, configuration and a stable idempotency_key. Reuse that key when retrying the same creation; use a new key for a separate source. Supply credentials through credential_handle. Workspace approval settings still apply. daspire_check_source verifies access, and daspire_discover_source retrieves stream schemas without starting a sync. For the Feishu employee roster, create a separate source with modules: ["ehr"]; keep existing approval sources and their selected streams unchanged.

daspire_reuse_native_activation_warehouse accepts name, destination_id, and optional execution_mode. It creates a Native read reference to an existing scoped MySQL warehouse credential binding. It does not accept passwords or return destination credentials. Normal workspace approvals and Native read compatibility checks apply. Use daspire_probe_native_activation_source to check and discover the returned source before configuring an Activation.