MCP

Combined exposes a stateless, read-only MCP data surface at:

https://platform.trycombined.com/mcp?account_id=ACCOUNT_UUID

The Account ID is required and fixes tenant scope. Each request authenticates again, resolves current grants, and validates the HTTP Origin when present. The endpoint does not create a durable MCP session and never broadens the credential's access.

Authentication and discovery

OAuth-capable clients should connect to the MCP URL directly. A 401 challenge advertises protected-resource metadata at /.well-known/oauth-protected-resource/mcp; that metadata identifies the authorization server and binds issued access tokens to this resource. Compatible agent clients can also discover the WorkOS Agent Auth guide through the authorization-server metadata.

For an unattended runtime, provide its provisioned credential as a secret environment variable:

{
  "type": "streamable-http",
  "url": "https://platform.trycombined.com/mcp?account_id=${COMBINED_ACCOUNT_ID}",
  "headers": {
    "Authorization": "Bearer ${COMBINED_TOKEN}"
  }
}

Do not replace ${COMBINED_TOKEN} with a committed token. Environment interpolation syntax depends on the MCP client.

Claude Code

{
  "mcpServers": {
    "combined-context": {
      "type": "http",
      "url": "${COMBINED_API_URL}/mcp?account_id=${COMBINED_ACCOUNT_ID}",
      "headers": {
        "Authorization": "Bearer ${COMBINED_TOKEN}"
      }
    }
  }
}

Run claude mcp list to verify that the server is reachable. Generate a client-specific configuration from the product's Access workspace when possible.

Tools

`list_sources`

Returns granted Sources, state, and freshness. limit defaults to 50 and cannot exceed 100. Continue with the opaque cursor returned by the preceding page; do not inspect or construct cursors.

`list_datasets`

Lists logical datasets for one sourceId, with the same cursor pagination model. Use it to discover SQL relation names rather than guessing physical storage names.

`describe_dataset`

Returns fields, logical types, classifications, and freshness for one datasetId. Call it before writing SQL when the schema is not already known.

`query_sql`

Executes the same bounded, read-only query path as POST /v1/sql.

sql is limited to 16 KiB.
parameters supports at most 100 positional values.
maxRows defaults to 100 and cannot exceed 1,000.
Only one bounded SELECT over granted logical relations is accepted.

Use ? placeholders for values. Never interpolate untrusted values or identifiers into SQL.

{
  "sql": "SELECT channel_name, COUNT(*) AS messages FROM slack_messages WHERE sent_at >= ? GROUP BY channel_name ORDER BY messages DESC LIMIT 20",
  "parameters": ["2026-08-01T00:00:00Z"],
  "maxRows": 20
}

The result includes typed structuredContent. Large text values can have a bounded human-readable preview while the complete permitted value remains structured. Client cancellation is forwarded to the query worker.

`get_freshness`

Returns Source and dataset freshness facts for up to eight sourceIds. Use it before presenting time-sensitive findings and state the relevant lastSuccessAt or expected freshness in the answer.

`search_context`

Performs bounded literal substring search over eligible text fields. It is not semantic or vector search.

Scope to at most 8 Sources and 24 datasets.
limit defaults to 25 and cannot exceed 100.
Search covers at most 24 fields in total and 3 fields per dataset.
The response includes coverage so the agent can disclose what was and was not searched.

Use search_context for fast phrase lookup. Use catalogue discovery plus query_sql when you need joins, aggregates, exact filters, or explicit control over fields.

Recommended agent workflow

Call list_sources and reject an unexpected Account or Source scope.
Call list_datasets and describe_dataset to learn logical names and fields.
Check freshness when the question depends on recency.
Query with parameters and the smallest useful maxRows.
Report Sources, time bounds, truncation, coverage, and uncertainty with the answer.

Errors

An authentication failure returns 401 and a WWW-Authenticate discovery challenge. Missing grants return 403; an invisible or missing resource returns 404; SQL policy and validation failures return 422; rate or resource bounds return 429, sometimes with Retry-After; temporary dependencies return 503.

MCP tool errors include an actionable message and correlation ID. Preserve that ID when troubleshooting, but never include the bearer token or returned content in a diagnostic report. See Query and MCP troubleshooting.

On this page