Skip to content

Connect AI assistants

Connect Claude, Claude Code, Codex, or another MCP client that supports remote servers with sign-in to a project's data. You sign in as yourself and ask questions in plain language.

The data MCP server must be turned on for the project first. An admin does that. See MCP config.

Find your connector URL

Open the project, then MCP config. The Share tab shows the connector URL:

https://data.dagctl.io/projects/<project id>/mcp

Each project has its own URL. The steps below use the name dagctl-<project>, which the Share tab fills in for you.

Connect

For claude.ai and the desktop app.

  1. Open Settings → Connectors → Add custom connector. Enter a name and the connector URL.
  2. Click Connect and sign in to dagctl.
  3. Ask a question about the project's data.

Note

On Team and Enterprise plans, an owner may need to add the connector first.

  1. Add the connector. Run this in your terminal.

    claude mcp add --transport http dagctl-<project> https://data.dagctl.io/projects/<project id>/mcp

  2. Sign in. Open Claude Code, type /mcp, choose dagctl-<project> and sign in.

  1. Add the connector.

    codex mcp add dagctl-<project> --url https://data.dagctl.io/projects/<project id>/mcp

  2. Sign in. Adding the server does not sign you in.

    codex mcp login dagctl-<project>

Add the connector URL to any client that supports remote MCP servers with sign-in. The client finds dagctl's sign-in page on its own.

To test from a terminal, use a token.

Ask your first question

Use dagctl to list the models in this project, then show me the ten most recent rows from the biggest one.

The assistant has five tools: list_models, get_model, search_definitions, run_query and ping. It only runs one SELECT at a time. It is limited to models your admin shared. Your warehouse grants decide what it can actually read.

What SQL is accepted depends on the warehouse: one SELECT, no scripting, no system views. When BigQuery is available (coming soon), each query also has a scan cap, set by your admin.

Use a token instead

Bots and scripts use a query token. An admin creates it under MCP config → Tokens. Save it as an environment variable named DAGCTL_QUERY_TOKEN. The snippets read it from there. Never paste the token into the chat.

Put this in .mcp.json.

{"mcpServers":{"dagctl-<project>":{"type":"http","url":"https://data.dagctl.io/projects/<project id>/mcp","headers":{"Authorization":"Bearer ${DAGCTL_QUERY_TOKEN}"}}}}

Put this in ~/.codex/config.toml.

[mcp_servers.dagctl-<project>]
url = "https://data.dagctl.io/projects/<project id>/mcp"
bearer_token_env_var = "DAGCTL_QUERY_TOKEN"

curl -s https://data.dagctl.io/projects/<project id>/mcp -H "Authorization: Bearer $DAGCTL_QUERY_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Note

A client that can't read environment variables in its config needs the token pasted into its header setting. Keep that file out of version control.

Messages you may see

The assistant shows these as written. Most end with Reference: <id>. Give that id to your admin, who can find the query in the query log.

Message What to do
That model isn't shared with this connector. Use list_models to see what is. Ask the assistant to run list_models. Ask an admin to share the model.
Query rejected: ... Only one read-only SELECT can run. Ask for a single SELECT. No writes, no multiple statements.
Warehouse error: ... The warehouse refused the query. Fix the SQL, or check with your admin if it repeats.
The query exceeded its Ns time limit. Narrow it and retry. Add filters or select fewer columns.
This query would scan more than this project's limit of N GB. Add filters, select fewer columns or filter on the partition column. An admin can raise the limit. (BigQuery, coming soon) Do what the message says, or ask an admin to raise the limit.
The query or its result is too large. Add filters or a LIMIT. Add filters or a LIMIT.
The query service is busy. Retry in a few seconds. Wait and retry.
This project is already running its maximum number of queries. Retry shortly. Wait and retry. An admin can raise the limit.
This project reached its daily query limit. It resets at midnight UTC. Ask your data team to raise it. Wait until midnight UTC, or ask an admin to raise the daily budget.
The query service for this project isn't ready yet. Retry in a few minutes. It is starting or restarting. Wait and retry.
You're sending queries too quickly for this project. Wait a moment and retry. Slow down, especially in scripts.
The data service is temporarily unavailable. Retry in a few seconds. Wait and retry.
The query couldn't be completed. Retry. If it repeats, send the Reference to your admin.

The connector says "not authorized". Sign in again: /mcp in Claude Code, codex mcp login dagctl-<project> in Codex, or reconnect in Claude. If it still fails, ask an admin whether the data MCP server is on and whether your role can query.