# MCP Gateway
source: https://docs.chalk.ai/docs/mcp-gateway

## Register, secure, and govern the external MCP servers your agents connect to.

The Chalk MCP Gateway is a control plane for the external
Model Context Protocol (MCP) servers your agents use. Instead
of pointing each agent at a handful of MCP servers directly — each with its own URL, credentials,
and trust assumptions — you register those servers once with the gateway. The gateway aggregates
their tools, resources, and prompts behind a single connection, holds the credentials, enforces
who may call what, and records every tool call.

The MCP Gateway is distinct from the MCP Server. The MCP Server exposes
Chalk itself to agents (run queries, execute ChalkSQL, inspect your deployment). The MCP
Gateway sits in front of other MCP servers and governs your agents' access to them.

### Registering MCP servers

Register and manage backend servers from the Data Sources → MCP servers section of the Chalk
dashboard. Each server has:

| Field          | Description                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------ |
| **Name**       | A unique name for the backend.                                                                   |
| **Transport**  | `HTTP` for a remote server (set a URL), or `stdio` for a local process (set a command and args). |
| **Credential** | The credential used to connect (see [Credentials](#credentials)).                                |

Once a server is registered and connected, the dashboard shows its connection status and lets you
browse everything it exposes — its tools (with input schemas), resources (with URI, MIME
type, and description), and prompts (with arguments) — and call a tool directly from the UI to
verify it works.

### Credentials

Credentials are stored with the gateway, not with the agents, so secrets never have to be
distributed to clients. The gateway supports several credential kinds to match how each backend
authenticates:

| Kind                      | Use for                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| **Bearer token**          | A server that accepts a static `Authorization: Bearer` token.                            |
| **Headers**               | A server that needs one or more custom HTTP headers.                                     |
| **Environment variables** | A `stdio` server that reads secrets from its environment.                                |
| **OAuth (user)**          | A server behind an OAuth 2.0 user flow (authorize/token URLs, client id/secret, scopes). |
| **OAuth (DCR)**           | A server that supports OAuth Dynamic Client Registration (issuer + scopes).              |

For OAuth-backed servers, each user links their own account, so calls run with that user's
identity rather than a shared credential.

### Authorization policies

The gateway enforces Rego policies on every tool call, so you can decide which agents and
users may call which tools — and under what arguments — independent of the backend itself. A
policy has a name, Rego source, and an enabled flag, so you can store a policy and turn it on or
off without deleting it.

To develop a policy safely, simulate it against a hypothetical tool call (a user, scopes,
backend, tool, and arguments) and inspect the resulting allow/deny decision and its reasons before
enabling it. At request time, each call is checked against the active policy and either allowed or
denied with explicit reasons.

Beyond per-tool policies, you can also scope an agent to a fixed set of allowed backends, so a
given agent only ever sees the servers it is meant to use.

### Audit log

Every tool call the gateway handles is recorded. The recent audit feed shows, for each call:

| Field                 | Description                                |
| --------------------- | ------------------------------------------ |
| **Timestamp**         | When the call was recorded.                |
| **Agent**             | The agent (or user) that made the call.    |
| **Backend / tool**    | Which server and tool were invoked.        |
| **Decision**          | `allow`, `deny`, or `error`.               |
| **Deny reasons**      | Why a call was denied, when applicable.    |
| **Arguments preview** | A truncated preview of the call arguments. |
| **Duration**          | How long the call took, in milliseconds.   |

This gives you a single place to see what your agents are actually doing across every backend.

### See also

- MCP Server — connect agents to your Chalk deployment over MCP.
- AI Router — an OpenAI-compatible LLM gateway for your Chalk deployment.