Connect an MCP client

Status: available (self-host); hosted endpoint rolling out. Run the MCP server yourself today (the mcp service in infra/docker-compose.yml, or Dockerfile.mcp on its own). A hosted public endpoint is being finalized behind a load balancer — once live, its URL shows in Settings → Connect AI (which also has the copy-paste client config). See MCP server for the what-and-why.

Goal

You'll point an MCP-capable LLM client — Claude Desktop, the claude CLI, Cursor, or any MCP client — at PLACEHOLDER Cloud's MCP server, authenticate with a personal API key, and drive your data-quality workflow in natural language: "list my datasources", "run the nightly orders checkpoint", "show me unacknowledged anomalies".

Prereqs

• A running PLACEHOLDER Cloud (the REST API the MCP server proxies to).
• A reachable MCP server — the hosted instance (its URL is shown in Settings → Connect AI), or one you run yourself (https://<mcp-host>/mcp; default port 8080).
• An MCP client that supports the Streamable HTTP transport with a bearer-token header.
• A personal API key (dqk_…). Mint one per Create an API token — Settings → API keys → New API key. Scope it to the workspace you want the client to act in (or leave it at full org access).

The key acts as you: it carries your org role and (if you set one) your workspace scope. The MCP server forwards it to the REST API, which enforces the same org / workspace / role isolation it always does. Treat the key like a password and store it in your client's secret store, not in a checked-in config file.

Steps

1. Mint the key. Follow Create an API token. Copy the dqk_… value — it's shown exactly once.

2. Find the MCP endpoint. It's https://<mcp-host>/mcp. If you're running it from compose locally, that's http://localhost:8080/mcp. (The /mcp path is the MCP Streamable-HTTP endpoint; GET /health is just the liveness probe.)

3. Add the server to your client, supplying the URL and the Authorization: Bearer dqk_… header.

   Claude Desktop / claude CLI — add it as a remote (HTTP) MCP server. With the CLI:

   claude mcp add --transport http dq-cloud https://<mcp-host>/mcp \
     --header "Authorization: Bearer dqk_..."

   Or in the client's MCP config JSON:

   {
     "mcpServers": {
       "dq-cloud": {
         "type": "http",
         "url": "https://<mcp-host>/mcp",
         "headers": { "Authorization": "Bearer dqk_..." }
       }
     }
   }

   Cursor / other clients — use the same URL, transport http (Streamable HTTP), and an Authorization: Bearer dqk_… header. The exact UI differs per client; the three inputs are always URL, transport, header.

4. Reload / reconnect so the client opens an MCP session against /mcp.

What tools appear

Once connected, the client lists the 31 tools the server exposes, grouped by resource (datasources, assets, profiling, rule suites, checkpoints, results, anomalies, suggestions, alert rules, schedules, plus whoami and expectation_gallery). See the full catalogue. You won't call them by name — you ask the model in plain language and it picks the tools.

Try it

Ask the model:

• "Who am I connected as?" → the model calls whoami and reports your user, org, workspace scope, and role. This is the fastest way to confirm auth works.
• "List my datasources." → datasources_list. You'll get the datasources visible to your key's scope.
• "Run the checkpoint called orders-nightly and tell me if it passed." → the model resolves the checkpoint (checkpoints_list / checkpoints_get), triggers it (checkpoints_run), then polls the outcome (checkpoints_run_get) and summarises pass/fail for you.

Verify

• "Who am I connected as?" returns your identity and the expected org / workspace scope — not someone else's, and not broader than the key you minted.
• A list call returns only resources inside your key's scope. If you scoped the key to one workspace, datasources in other workspaces don't appear.
• Revoke the key in Settings → API keys; within the API's TOKEN_CACHE_TTL_SECONDS window (default 5s) the next tool call fails with an auth error. Re-mint and reconnect to restore access.

Caveats

• One credential, same access. The MCP server adds no privileges. A viewer-role key can list and read but gets a 403 (surfaced to the model as an error) on create/update tools. Scope deliberately.
• No server-side AI. The intelligence is your client's model — the server only forwards primitive calls. A smarter model gives a better experience with no server change. See the primitives philosophy.
• Bearer auth today; OAuth later. Pasting a long-lived dqk_… bearer is the supported path now. OAuth 2.1 + Dynamic Client Registration is on the roadmap.
• Not behind IAP. If your PLACEHOLDER Cloud sits behind Google IAP, note the MCP server is deliberately not — an MCP client can't complete IAP's browser SSO. It carries its own dqk_ bearer instead. Self-host it with public ingress accordingly.