# Chalk CLI Reference: MCP Gateway
source: https://docs.chalk.ai/cli#mcp-gateway

Manage the MCP gateway's servers, Rego policies, and agents declaratively: export the live configuration to a manifest, edit it, and apply it back.

## `chalk mcp-gateway apply`
source: https://docs.chalk.ai/cli?command=mcp_gateway_apply

```bash
chalk mcp-gateway apply
```

Use the `apply` command to create and update MCP gateway servers, policies, and agents from a manifest.

The manifest uses the gateway's seed file format: a `backends` list (`servers` is accepted as an alias) whose credentials name the environment variables holding each secret, plus optional `policies` and `agents` lists. Files written by `chalk-mcp-gateway import-litellm` or for `chalk-mcp-gateway seed-backends` apply unchanged, and JSON or YAML both work.

```
{
  "backends": [
    {"name": "linear", "transport": "http",
     "url": "https://mcp.linear.app/mcp",
     "credentials": {"type": "bearer", "token_env": "LINEAR_API_KEY"}},
    {"name": "notion", "transport": "stdio", "command": "npx",
     "args": ["-y", "@notionhq/notion-mcp-server"],
     "credentials": {"type": "env",
                     "vars": {"NOTION_TOKEN": "NOTION_API_KEY"}}},
    {"name": "brex", "transport": "http", "url": "https://api.brex.com/mcp",
     "credentials": {"type": "oauth_dcr"},
     "access": {"groups": ["Finance"], "users": ["cfo@example.com"]}}
  ],
  "policies": [{"name": "deny-writes",
                "source_file": "policies/deny-writes.rego"},
               {"name": "linear-readonly", "backends": ["linear"],
                "source_file": "policies/linear-readonly.rego"}],
  "agents": [{"name": "support-bot", "allowed_backends": ["linear"]}]
}
```

The command reads the live configuration, prints a plan of what it will create, update, and leave unchanged, and then applies it. Updates are partial: a field the manifest leaves out keeps its stored value, and an update sends only the fields that changed. Set `"credentials": null` to remove a server's credential. `base_url`, `allowed_tools`, `tool_overrides`, `instructions`, and `caller_identity` follow the same rule; set an empty value (`[]`, `{}`, or `""`) to clear one.

A policy's `backends` binds it to those servers: the gateway evaluates it only for calls to them, plus every policy with no binding. Leaving `backends` out keeps the stored binding, including one set in the dashboard, so editing a bound policy's source never makes it global. Set `"backends": []` to make a policy apply to every server.

A server's `access` block limits it to the Chalk users it lists (by id or email) and the members of the Chalk groups it lists (by id or name). Everyone else has the server hidden from their tool listings and every call to it refused. `apply` resolves names and emails to group and user ids against your team and writes the block as a generated `backend_deny` policy named `server-access:<server>`, bound to that server alone, before creating the server. The policy matches users on the caller's user id and groups on the `chalk.ai/groups` claim of the caller's Chalk token, so group membership changes take effect without re-running `apply`. Leaving `access` out keeps the stored allowlist; `"access": null` removes it. An access block governs who may use a server, not who may manage it: anyone without an agent allowlist can still edit the server and its access policy.

Secrets never appear in the manifest. Credential blocks name environment variables (`token_env`, `vars`, `client_id_env`, `client_secret_env`), and `${VAR}` placeholders in any string are interpolated from the environment (`$${` is a literal `${`). Every placeholder and credential variable is resolved, and the whole manifest validated, before anything is written. A credential block that names only its `type` -- as [`export`](https://docs.chalk.ai/cli?command=mcp-gateway_export) writes them -- keeps the stored credential.

Writes stop at the first failure, and the error lists the changes already applied.

**Flags**

- `-f, --file <path>` (string)
  Manifest to apply: a JSON or YAML file, a directory of them (merged), or `-` for stdin. The gateway's `seed-backends` seed files are accepted as-is.
- `--dry-run <dry-run>` (bool, default `false`)
  Print the plan without changing anything. Credential environment variables must still be set, so a dry run also checks that the apply would not fail on a missing secret.
- `--prune <prune>` (bool, default `false`)
  Delete live servers, policies, and agents that the manifest does not list. Only sections present in the manifest are pruned: a file without a `policies` key never deletes a policy. Asks for confirmation unless `--yes` is passed.
- `-y, --yes <yes>` (bool, default `false`)
  Skip the confirmation prompt for deletions made by `--prune`. Required to prune when stdin is not a terminal.
- `--rotate-credentials <rotate-credentials>` (bool, default `false`)
  Re-send every credential whose environment variables are named in the manifest, even when the stored credential already has the same kind. Without it, a same-kind credential is left as stored because the API never returns secret values to compare.

**Example**

```
$ chalk mcp-gateway apply -f gateway.json --dry-run
  + create     policy  server-access:brex  source, enabled=true, backends  (allows groups Finance and 1 user(s); applies only to brex)
  + create     server  brex             transport=http, url, credential=oauth_dcr
  + create     server  sentry           transport=http, url, credential=oauth_dcr
  ~ update     server  linear           url
  = unchanged  server  notion
  + create     policy  deny-writes      source, enabled=true
  ~ update     policy  linear-readonly  backends  (applies only to linear)
Plan: 4 to create, 2 to update, 0 to delete, 1 unchanged.
Dry run: no changes were applied.

$ chalk mcp-gateway apply -f gateway/ --prune --yes
```

## `chalk mcp-gateway export`
source: https://docs.chalk.ai/cli?command=mcp_gateway_export

```bash
chalk mcp-gateway export
```

Use the `export` command to write the live MCP gateway servers, policies, and agents in the manifest format that [`apply`](https://docs.chalk.ai/cli?command=mcp-gateway_apply) reads, so `export`, edit, `apply` round-trips.

Secrets are never exported. Each server's credential is written as a block naming only its `type`, which `apply` reads as "keep the stored credential". To set or rotate one, replace the block with one that names the environment variables holding the secret.

Each server's `base_url`, tool shaping (`allowed_tools`, `tool_overrides`, `instructions`), and `caller_identity` are exported as stored, as is each policy bound to specific servers' `backends`. A server's generated `server-access:<server>` policy is exported as that server's `access` block, with its groups and users written as ids. OAuth settings that live inside the credential (`token_auth_method`, `resource`, `resource_indicator`) are not, since the API returns only the credential's kind.

**Flags**

- `-o, --output <path>` (string)
  Write the manifest to this file instead of stdout.

**Example**

```
$ chalk mcp-gateway export -o gateway.json
✓ Wrote 3 servers, 1 policy, and 2 agents to gateway.json
```

## `chalk mcp-gateway servers list`
source: https://docs.chalk.ai/cli?command=mcp_gateway_servers_list

```bash
chalk mcp-gateway servers list
```

Use the `list` command to list the MCP servers (backends) registered with the environment's gateway.

**Example**

```
$ chalk mcp-gateway servers list
 Name     Transport  Target                               Credential  Registered
 linear   http       https://mcp.linear.app/mcp           bearer      yes
 notion   stdio      npx -y @notionhq/notion-mcp-server   env         yes
```

## `chalk mcp-gateway servers get`
source: https://docs.chalk.ai/cli?command=mcp_gateway_servers_get

```bash
chalk mcp-gateway servers get <name>
```

Use the `get` command to show one MCP gateway server. Credential values are never shown, only their kind.

**Arguments**

- `name` (string)
  The server's name.

**Example**

```
$ chalk mcp-gateway servers get linear
```

## `chalk mcp-gateway servers delete`
source: https://docs.chalk.ai/cli?command=mcp_gateway_servers_delete

```bash
chalk mcp-gateway servers delete <name>
```

Use the `delete` command to delete one MCP gateway server. It asks for confirmation unless `--yes` is passed.

**Arguments**

- `name` (string)
  The server's name.

**Flags**

- `-y, --yes <yes>` (bool, default `false`)
  Skip the confirmation prompt. Required when stdin is not a terminal.

**Example**

```
$ chalk mcp-gateway servers delete my-server --yes
```

## `chalk mcp-gateway servers callback_url`
source: https://docs.chalk.ai/cli?command=mcp_gateway_servers_callback_url

```bash
chalk mcp-gateway servers callback-url <name>
```

Use the `callback-url` command to print the OAuth redirect URI to register (allowlist) with the provider of a per-user OAuth MCP server, such as the redirect URIs list on a GitHub, Slack, or Atlassian OAuth app.

Link flows started from the Chalk dashboard or API server send the provider back to the API server's host, not to the gateway itself, so the URL is on the same host the CLI talks to (`--api-host`).

For `oauth_dcr` servers the gateway registers its own OAuth client, with these URLs, through dynamic client registration, so there is usually nothing to allowlist.

**Arguments**

- `name` (string)
  The server's name.

**Example**

```
$ chalk mcp-gateway servers callback-url github
https://api.chalk.ai/v1/mcp/oauth/callback
```

## `chalk mcp-gateway policies list`
source: https://docs.chalk.ai/cli?command=mcp_gateway_policies_list

```bash
chalk mcp-gateway policies list
```

Use the `list` command to list the Rego policies stored in the environment's MCP gateway.

The `Servers` column shows the servers a policy is bound to, or `all` for a global policy, which the gateway evaluates for every server.

**Example**

```
$ chalk mcp-gateway policies list
 Name             Enabled  Servers  Updated               Lines
 deny-writes      yes      all      2026-11-04T12:00:00Z  14
 linear-readonly  yes      linear   2026-11-05T09:30:00Z  8
```

## `chalk mcp-gateway policies get`
source: https://docs.chalk.ai/cli?command=mcp_gateway_policies_get

```bash
chalk mcp-gateway policies get <name>
```

Use the `get` command to print one MCP gateway policy, including its Rego source and the servers it is bound to (`all` for a global policy).

**Arguments**

- `name` (string)
  The policy's name.

**Example**

```
$ chalk mcp-gateway policies get deny-writes
```

## `chalk mcp-gateway policies delete`
source: https://docs.chalk.ai/cli?command=mcp_gateway_policies_delete

```bash
chalk mcp-gateway policies delete <name>
```

Use the `delete` command to delete one MCP gateway policy. It asks for confirmation unless `--yes` is passed.

**Arguments**

- `name` (string)
  The policy's name.

**Flags**

- `-y, --yes <yes>` (bool, default `false`)
  Skip the confirmation prompt. Required when stdin is not a terminal.

**Example**

```
$ chalk mcp-gateway policies delete my-policy --yes
```

## `chalk mcp-gateway agents list`
source: https://docs.chalk.ai/cli?command=mcp_gateway_agents_list

```bash
chalk mcp-gateway agents list
```

Use the `list` command to list the agents configured in the environment's MCP gateway and the servers each may use.

**Example**

```
$ chalk mcp-gateway agents list
 Name         Allowed Backends
 support-bot  linear, notion
```

## `chalk mcp-gateway agents get`
source: https://docs.chalk.ai/cli?command=mcp_gateway_agents_get

```bash
chalk mcp-gateway agents get <name>
```

Use the `get` command to show one MCP gateway agent and the servers it may use.

**Arguments**

- `name` (string)
  The agent's name.

**Example**

```
$ chalk mcp-gateway agents get support-bot
```

## `chalk mcp-gateway agents delete`
source: https://docs.chalk.ai/cli?command=mcp_gateway_agents_delete

```bash
chalk mcp-gateway agents delete <name>
```

Use the `delete` command to delete one MCP gateway agent. It asks for confirmation unless `--yes` is passed.

**Arguments**

- `name` (string)
  The agent's name.

**Flags**

- `-y, --yes <yes>` (bool, default `false`)
  Skip the confirmation prompt. Required when stdin is not a terminal.

**Example**

```
$ chalk mcp-gateway agents delete my-agent --yes
```
