跳到主要内容

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​

Feishu Native 1.2.0 candidate directory streams use the existing source create/update/check/discover and pipeline tools below. Once the candidate is activated, choose ehr_departments and/or ehr_users in source modules, then select those streams in the connection. See the Feishu setup guide for permission requirements and activation status. There is no separate department or user lookup MCP tool.

  • 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_get_pipeline

  • 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_cancel_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.

daspire_get_pipeline reads stored metadata without refreshing discovery by default. The underlying GET /api/control/v1/pipelines/{pipelineId} also treats an omitted or empty withRefreshedCatalog query parameter as false.

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. Connection deletion succeeds only after the platform confirms the connection is deleted. Native connections first stop future scheduling and require no queued or running job; cancel and reconcile any active job before retrying deletion. Historical jobs and retry snapshots are retained, while new execution is blocked. If a response is uncertain, read the connection and approval outcome before retrying.

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.

Use daspire_get_pipeline with pipeline_id to read an existing connection. Set with_refreshed_catalog: true only when requesting a fresh catalog: Native-owned connections use admitted Native discovery, publish a source-bound receipt, preserve selections and leave new streams unselected. This does not start a sync or change credentials or scheduling. Saved Native sources with older unannotated specs inherit the catalog capability without a customer resave; unsupported image/protocol combinations fail explicitly.

For an existing connection, daspire_apply_pipeline accepts a payload.pipeline_id and only the intended stream/settings changes. Set execution_mode: "proposal" to require an approval proposal. The platform rehydrates schemas, validates the discovery receipt and rechecks source/image and connection metadata under the update guard before publishing future execution material. Approval execution revalidates the catalog and rejects changed approved schemas. If a response is uncertain, read the pipeline and approval outcome before submitting another edit.

{
  "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. The browser pagination helper keeps unaffected connections visible when one Native status read is unavailable; the affected active row displays Status unavailable (status: unavailable, latestSyncJobStatus: unavailable, nativeScheduleState: unavailable). configuredStatus preserves its configuration; paused connections remain paused. Unconfirmed schedule details are cleared. These rows have an unavailable filter and count as attention, separately from incomplete setup. A successful refresh restores the current status automatically. No old legacy success is substituted. Direct inventory and status reads remain fail-closed errors. The web page's filters, pagination and health totals use the same projected results.

The same Connection read surface exposes nativeScheduleEnabled, nativeScheduleBlocked, nativePendingDestinationCommit and retained blocked occurrences. DESTINATION_COMMIT_RECEIPT_PENDING means the write is confirmed but its original receipt/accounting protection has not closed. A null lastVerifiedAt remains unreported; a ledger transition is not a new target lookup. Current protection is independent of historical lastSkip. These are additive read fields, with no new MCP recovery command or write permission.

waiting_source_maintenance means another pipeline using the same Source has an unfinished maintenance or recovery operation. Keep the original job and command identity while observing it; status reads do not start another writer or release its protection. The existing daspire_get_job tool reports the retained status. This reason requires the qualified execution receiver and its schema; installing a qualification package alone does not enable it.

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. Native-owned connections read retained history and job details without depending on execution readiness or the old per-connection route list. Reads do not submit syncs or refresh execution callbacks. An unavailable history projection 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.

Native sync queue status​

Native jobs waiting to start or retry return pending. The server's state_reason distinguishes queued, starting, waiting_retry, waiting_destination, and waiting_source_spool (temporary source-storage capacity is unavailable). createdAt records creation, and is not evidence that execution started; startedAt is absent until a runtime start is known. Connections expose hasActiveJob separately from isSyncing, and queued jobs keep Sync disabled. A completed partial_success remains a partial result. Use the same original command_id after an uncertain submission; do not create another sync to check progress. Queue counts are observations, not a promised position or ETA.

SOURCE_SPOOL_CAPACITY_EXHAUSTED means a running source reached its qualified temporary-storage limit. Its retained input is not proof of a destination commit. This terminal result differs from waiting_source_spool, which waits before source admission. Check the original job and its recovery status; do not submit another sync automatically or treat it as a destination authentication failure.

Native jobs also expose state_revision, queued_at, starting_at, process_started_at, finished_at, wait_reason, and observed_at when known. Use the revision to identify stale observations. Unknown process start times remain absent.

Pipeline listing also returns optional nativeScheduleLastSkip: scheduledFor and observedAt are epoch seconds, and reason is ACTIVE_EXECUTION, OCCURRENCE_OWNED_BY_RECOVERY, or AMBIGUOUS_DESTINATION_COMMIT. The latter means the runtime advanced the cadence without creating a job because the same pipeline has an unresolved destination outcome. Null means no observation is available. This is the latest recorded skipped occurrence, retained across later successful runs and schedule edits; it is not a failed job, a queue position, or a catch-up request. The gateway forwards this server-owned metadata without inferring a reason.

Use daspire_cancel_job with the opaque product job_id returned by job history. Use daspire_get_job and the approval tools to read back an uncertain result. Direct and approved cancellations use the shared runtime adapter and the existing workspace approval policy. Cancel an active job and verify its terminal state before retrying connection deletion; cancellation does not submit a replacement sync.

Enabled schedules with an unconfirmed destination outcome​

When deployed, nativeScheduleBlocked distinguishes the enabled schedule from current blocking; latestSyncJobStatus retains the actual most recent sync result. The UI uses the existing Broken state and shows Enabled · blocked while an original destination outcome needs confirmation. A recent sync failure alone does not mean that scheduling is blocked. nativePendingDestinationCommit contains the current reason, pending count and original commit/job/attempt IDs, duration start, last reported verification, alert and next action. Historical start times are labelled estimates; a null time/result means not reported, never confirmed uncommitted.

nativeScheduleBlockedOccurrences exposes up to twelve recent real appointments from existing diagnostic logs, with their original occurrenceKey, reason, scheduledFor, observedAt and original commits. These are scheduling decisions, not failed sync jobs, usage or checkpoints. Older retained entries remain on the original job's diagnostic log. The normal log retention still applies.

VERIFICATION_FAILED, VERIFICATION_STALLED and VERIFICATION_NOT_REPORTED require attention. The one-hour attention threshold does not expire commit protection or grant retry/write permission. Unknown outcomes remain protected while automatic verification continues. These status fields provide observations; they never authorize another write. After safe original settlement the current block clears, while appointment history and the real latest failed sync remain. The next natural appointment resumes without resaving or Sync Now; skipped appointments are not batch-replayed.

Native pipeline edits, including pause/resume, use the private compatibility metadata consumer behind Control, so retired legacy ingress does not block edits. Known metadata conflicts return an actionable HTTP 409 message. Read the pipeline after an uncertain edit; a previously disabled runtime schedule requires operator reconciliation. Cancelling a queued Native job uses its Native owner directly, including migrated connections, and projects the resulting lifecycle.