MCP Server

Chalk hosts a Model Context Protocol (MCP) server so that AI agents — Claude, Cursor, your own LangChain/agent code, or any MCP-compatible client — can interact with your Chalk deployment directly. Through the MCP server an agent can run online queries, execute ChalkSQL, read feature and resolver definitions, search logs and traces, and inspect query errors, all scoped to the permissions of the credentials it presents.

The MCP server is hosted alongside the Chalk API and requires no installation or self-hosting.

​

Endpoint

The server speaks the Streamable HTTP transport (MCP specification 2025-03-26). A single URL handles both the JSON-RPC POST requests and the Server-Sent Events (SSE) streams that the transport uses, so most clients only need this one URL. Despite the /sse suffix in the path, this is the modern Streamable HTTP transport rather than the deprecated HTTP+SSE transport — configure your client for a streamable-HTTP (or “HTTP”) remote server, not a legacy SSE server.

If you are on a dedicated or self-hosted Chalk deployment, replace api.chalk.ai with your own API server host. You can find it in the apiServer field of chalk config --format json.

​

Authentication

The MCP server authenticates with the same service credentials used everywhere else in Chalk. Provide your client_id and client_secret as HTTP headers on every request:

The server exchanges these for a short-lived access token internally, so you do not need to run the OAuth client-credentials flow yourself.

The credentials are sensitive — they can query and, depending on their permissions, modify your Chalk deployment. Treat them like any other secret and prefer a scoped service token over personal credentials.

​

Getting your credentials

Generate or look up a service token in the Settings → Service Tokens tab of the Chalk dashboard, then retrieve the values from the CLI with chalk config:

chalk config

Name           Value                                    Description
client_id      token-392c737aa1e467e42e85ae3e8417a003   default token
client_secret  ts-6307f46a00a68436b0f955b82b7fb30075d   default token
environment    btfxgaqqxbt7z                            ...
api_server     https://api.chalk.ai                     ...

To pull the values out programmatically, use a machine-readable format:

# JSON object with clientId / clientSecret / apiServer fields
chalk config --format json

# Shell export statements: CHALK_CLIENT_ID / CHALK_CLIENT_SECRET / ...
chalk config --format shell

​

Bearer tokens and OAuth

The server also accepts a standard Authorization: Bearer <access_token> header. If a request arrives without credentials, the server responds with 401 and a WWW-Authenticate challenge pointing at Chalk’s OAuth discovery endpoints (/.well-known/oauth-protected-resource), so MCP clients that implement the MCP authorization spec (including Dynamic Client Registration) can negotiate a token interactively. For headless and server-to-server use, the X-Chalk-Client-Id / X-Chalk-Client-Secret headers are the simplest option.

​

Selecting an environment

By default, requests run against the environment associated with your service token. To target a different environment, either:

• send the X-Chalk-Env-Id: <environment_id> header, or
• pass an environment_id argument to an individual tool call.

Environment overrides are only honored for user (personal) credentials. Use the list_environments tool to discover the environment IDs available to your team.

​

Connecting a client

Most MCP clients accept a remote server URL plus a set of headers. Use the streamable-HTTP / remote-server configuration for your client and point it at the endpoint above.

​

JSON configuration

This is the format used by Cursor, Windsurf, and many other clients (mcp.json / mcpServers):

{
  "mcpServers": {
    "chalk": {
      "url": "https://api.chalk.ai/v1/mcp/sse",
      "headers": {
        "X-Chalk-Client-Id": "token-392c737aa1e467e42e85ae3e8417a003",
        "X-Chalk-Client-Secret": "ts-6307f46a00a68436b0f955b82b7fb30075d"
      }
    }
  }
}

​

Claude Code

Add the server from the command line with claude mcp add:

claude mcp add --transport http chalk https://api.chalk.ai/v1/mcp/sse \
  --header "X-Chalk-Client-Id: $(chalk config --format json | jq -r .clientId)" \
  --header "X-Chalk-Client-Secret: $(chalk config --format json | jq -r .clientSecret)"

​

Clients that only support stdio

For a client that cannot connect to a remote server directly, bridge to it with mcp-remote:

{
  "mcpServers": {
    "chalk": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.chalk.ai/v1/mcp/sse",
        "--header",
        "X-Chalk-Client-Id: ${CHALK_CLIENT_ID}",
        "--header",
        "X-Chalk-Client-Secret: ${CHALK_CLIENT_SECRET}"
      ],
      "env": {
        "CHALK_CLIENT_ID": "token-392c737aa1e467e42e85ae3e8417a003",
        "CHALK_CLIENT_SECRET": "ts-6307f46a00a68436b0f955b82b7fb30075d"
      }
    }
  }
}

​

Verifying the connection with curl

You can confirm your credentials are accepted by issuing an initialize request directly:

curl -sS https://api.chalk.ai/v1/mcp/sse \
  -H "X-Chalk-Client-Id: $(chalk config --format json | jq -r .clientId)" \
  -H "X-Chalk-Client-Secret: $(chalk config --format json | jq -r .clientSecret)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

A 401 with a WWW-Authenticate header means the credentials were missing or rejected.

​

Available tools

The server exposes a set of tools for querying and operating your Chalk deployment. The exact set evolves over time, and the tools a given client can call depend on the permissions granted to its credentials — for example, run_online_query requires the query.online permission, and the observability tools require monitoring.read. Tools your token is not authorized for will return a permission error.

​

Queries and SQL

​

Metadata and discovery

​

Observability and debugging

Additional infrastructure and sandbox tools (Kubernetes deployment/node inspection, sandboxed Python execution, and similar) are available to credentials with the appropriate elevated permissions.

​

See also

• Authentication — service credentials and RBAC for the Chalk API.
• Development with LLMs — prompts for writing Chalk code with AI assistants.
• ChalkSQL — the SQL dialect available through execute_sql_query.