# MCP Server source: https://docs.chalk.ai/docs/mcp-server ## Connect AI agents to your Chalk deployment over the Model Context Protocol. 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: | Header | Value | | ----------------------- | ------------------------------------ | | `X-Chalk-Client-Id` | Your service token's `client_id` | | `X-Chalk-Client-Secret` | Your service token's `client_secret` | The server exchanges these for a short-lived access token internally, so you do not need to run the OAuth client-credentials flow yourself. ### 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 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: 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 | Tool | Description | | --------------------- | ----------------------------------------------------------------------------------- | | `run_online_query` | Run an online query for one or more features. | | `execute_sql_query` | Execute a [ChalkSQL](/docs/chalksql/what-is-chalk-sql) query, with preview support. | | `get_offline_queries` | List offline queries (batch jobs). | | `get_offline_query` | Fetch metadata for a single offline query. | ### Metadata and discovery | Tool | Description | | --------------------------------------------------- | ---------------------------------------------------------- | | `list_features` | List the features defined in the environment. | | `get_feature_definition` | Read a feature's definition and metadata. | | `list_resolvers` | List resolvers. | | `get_resolver_definition` | Read a resolver's definition and metadata. | | `list_functions` / `get_function` / `call_function` | List, inspect, and invoke external functions. | | `list_branches` | List the deployment's branches. | | `list_environments` | List environments available to your team (with their IDs). | | `search_deployment_source` | Search the deployed source code. | | `search_docs` | Search the Chalk documentation. | ### Observability and debugging | Tool | Description | | ----------------------- | ------------------------------------------------------------------ | | `get_query_errors` | List recorded query errors, with filtering and pagination. | | `get_query_plan_json` | Retrieve a query plan as JSON. | | `get_perf_summary_json` | Retrieve a query performance summary as JSON. | | `search_logs` | Search application logs for the environment. | | `search_traces` | Search distributed traces and their spans. | | `search_kube_events` | Search Kubernetes cluster events (scheduling, OOM kills, crashes). | 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.