MCP Client Setup

This guide shows how to connect MCP clients to Mission Control.

MCP server URL

Use the Setup MCP flow to get the MCP server URL for your Mission Control tenant.

1. In Mission Control, open the user menu and select Setup MCP.

   

2. Copy the MCP server URL from the setup dialog.

The MCP server URL uses one of these formats:

• SaaS users: https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp
• Self-hosted users: https://your.domain.com/api/mcp

Permissions

An AI agent connected through MCP has no permissions of its own. It acts as the person who connected it, so it can never see or do more than that person can in Mission Control.

On top of what that person can already do, MCP adds two actions that only MCP checks:

• mcp:use lets the person connect an agent at all. Without it, the MCP server refuses every request.
• mcp:run lets the person's agent run a playbook. It's granted per playbook, so it decides which playbooks agents can run.

Everything else the agent does is checked exactly as in the UI. If someone can't open a config, a view or a health check in the UI, their agent can't read it either. If they can't run a playbook from the UI, their agent can't run it, even with mcp:run.

Two things work the same through MCP as in the UI, and can reach data the person can't read directly:

• Views show whatever their queries return. Someone who can read a view sees its rows, even rows from configs they can't open.
• Playbook runs act as the playbook once they start. The person's permissions decide whether the run can start, but each action of the run, such as reading configs or using a connection, is checked as the playbook. If a run fails on a permission, the playbook needs it, not the person. See Playbooks, notifications and other automation.

So to let someone use MCP, an admin grants them mcp:use, and mcp:run on the playbooks their agent may run. Their existing permissions decide the rest. The sections below explain each step.

Connecting: mcp:use

mcp:use lets someone connect an agent to the MCP server. It doesn't let the agent read or run anything by itself. Without it, every request to the MCP server fails with 403 forbidden: user <id> does not have mcp:use permission, before any tool runs.

mcp:use acts on Mission Control itself, not on a resource, so a Role rule that grants it has only a name and the action, with no Scope:

Rule field	Value
name	use-mcp
action	mcp:use

To let people use MCP, an admin gives that Role to them, or to their teams, with a RoleBinding. Don't add a constraint to that RoleBinding: a rule without a resource, such as mcp:use, never applies through a RoleBinding with a constraint, so a constrained binding leaves people without mcp:use.

Reading data: the same permissions as the UI

Once connected, each tool and resource checks the same permission as the matching page of the UI, and returns only what the person may see. mcp:use doesn't grant any of these, so people need them from their other Roles.

Tools	Need
Catalog, changes, access, related configs	read on the configs. Results leave out the rest
Health check search and history	read on the checks
View tools	read on the view. Each readable view becomes a tool
run_health_check	create on canaries
Connections	read on connections. Credentials are never returned
Notifications	read on notifications
Jobs	job:read
eval_template	read on the config, change or check it loads

Running playbooks: mcp:run

mcp:run decides which playbooks an agent can run. It's granted per playbook, through the Scope of the rule that grants it, so it's how an admin turns MCP on or off for each playbook:

• A playbook appears as a tool only for people with mcp:run on it. A playbook outside every mcp:run Scope is never offered to an agent, even to someone who can run it from the UI.
• Running it through MCP then makes the same checks as running it from the UI: playbook:run on the playbook, with the config, component or check it runs on in the rule's target Scope, and read on that config, component or check. See Running playbooks: resource and target.

So to let a team run some playbooks from an agent, give them a Role with these rules, each on a Scope that selects those playbooks:

Rule action	Resource Scope	Target Scope
mcp:run	The playbooks to expose	None
playbook:run	The same playbooks	The configs they may run on, if any

The permissions quickstart shows a Role that grants playbook:run. Add an mcp:run rule on the same playbook Scope to offer those playbooks to agents.

The playbook's mcp field only changes how the tool is described to the agent, such as its title and hints. It doesn't grant or remove access.

When changes take effect

Mission Control builds the list of playbook and view tools when the client connects. After you grant or remove mcp:run, or read on a view, reconnect the client to see the new list. Every call still checks permissions when it runs, so a removed permission blocks the call immediately.

Choose an authentication method

Mission Control supports two ways to authenticate an MCP client. They differ in what the agent may do:

• OAuth: use an MCP client that supports OAuth for remote MCP servers. You sign in from a browser, and the agent has everything you have: only your own permissions are checked.
• Personal access token: create a Mission Control personal access token and add it to your MCP client configuration. The agent is also limited by the token's Roles: each check must be allowed both by you and by a rule of one of the token's Roles. See How a token is limited.

What a token's Roles must allow

The Roles of a token for MCP must cover every step the agent takes, not only yours:

The agent should	The token's Roles need
Connect	mcp:use. The Setup MCP flow adds a Role with it for you
Read the catalog, checks, views	read on what the agent should see
Run playbooks	mcp:run and playbook:run on those playbooks

If none of the token's Roles allows mcp:use, requests fail with 403 forbidden: the access token's roles don't grant mcp:use. A token's Roles can't change after it's created, so to give an agent more, create a new token.

OAuth

OAuth

Use this approach when your MCP client supports OAuth for remote MCP servers.

Point the client at the MCP server URL.

Mission Control prefers Client ID Metadata Documents (CIMD) for OAuth client registration. Compatible clients use an HTTPS metadata URL as the client ID. Mission Control fetches that document during authorization.

Clients that do not support CIMD fall back to Dynamic Client Registration (DCR) at /oauth/register.

The client discovers the authorization server, registers with CIMD or DCR, and opens a browser for you to sign in. On the consent screen, check the client name and redirect address before you allow access.

The agent acts with all your own permissions. You need mcp:use, and mcp:run on any playbook the agent should run. See Permissions.

Claude Code

Create or edit .mcp.json in your project root and add the Mission Control MCP server.

.mcp.json
{
  "mcpServers": {
    "mission-control": {
      "name": "mission-control",
      "type": "http",
      "url": "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp"
    }
  }
}

Then start Claude Code, run /mcp, select mission-control and choose Authenticate. Claude Code opens a browser to sign in to Mission Control. After you allow access, /mcp shows mission-control as connected with its tools.

VS Code

Create or edit .vscode/mcp.json in your project root and add the Mission Control MCP server.

.vscode/mcp.json
{
  "servers": {
    "mission-control": {
      "url": "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp"
    }
  },
  "inputs": []
}

Start the server from mcp.json. VS Code asks to authenticate with Mission Control and opens a browser to sign in. After you allow access, Mission Control's tools appear in Copilot Chat's tools list in agent mode.

Claude Desktop Connectors

Claude Desktop supports remote MCP servers through Connectors.

1. In Claude Desktop, open Settings → Connectors.
2. Select Add → Custom connector.

The Connectors page lists existing web connectors and custom connectors.

The Add custom connector dialog creates a remote MCP connector.

3. In Name, enter Mission-Control.
4. In Remote MCP server URL, enter your MCP server URL.
5. Leave OAuth Client ID and OAuth Client Secret empty.
6. Select Add.
7. On the Connectors page, select Connect for the Mission Control connector.
8. Complete the authentication flow.

Mission Control tools appear in Claude Desktop after the OAuth flow completes.

Personal Access Token

Personal access token

Use this approach when your MCP client doesn't support OAuth, or when you want to pass a Mission Control personal access token in the client configuration.

Create a personal access token

The agent can only do what both you and the token's Roles allow, so choose the token's Roles for what the agent should do. See What a token's Roles must allow.

1. In Mission Control, open the user menu and select Setup MCP.

   

2. Fill in the form:

   Field	Value
   Name	A name for the token, unique among your tokens
   Expiry	How long the token is valid. Defaults to 90 days
   Auto Renew	Extends the expiry while the token is in use
   Role Bindings	The Roles that limit the token. The form preselects a Role that allows mcp:use; keep it. Add Roles with read on what the agent should see, and with mcp:run and playbook:run on the playbooks it should run

   A token's Roles can't change later. If no Role grants what the agent needs, ask an admin to create one, then create the token.

3. Select Create Token, then copy the generated configuration for your MCP client, or copy the token value. Mission Control shows the token only once.

   

Authentication header

Send the token in the Authorization header as Bearer <token>. Every configuration that Setup MCP generates, and every example below, uses this form.

Clients that only support basic authentication can use the username token and the token as the password. The header is then Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of token:<token>.

Configure a client

Replace <token> with your token and the URL with your MCP server URL. Clients that can't send headers to a remote MCP server use the mcp-remote bridge, which runs locally through npx and needs Node.js.

Claude Desktop

1. Open Claude Desktop settings.
2. Select Developer → Edit Config.
3. Add the Mission Control MCP server configuration:

claude_desktop_config.json
{
  "mcpServers": {
    "mission-control": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp",
        "--header",
        "Authorization:Bearer <token>"
      ]
    }
  }
}

4. Restart Claude Desktop. Mission Control's tools appear in the tools menu.

Claude Code

1. Create or edit .mcp.json in your project root and add the Mission Control MCP server:

.mcp.json
{
  "mcpServers": {
    "mission-control": {
      "name": "mission-control",
      "type": "http",
      "url": "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

2. Restart Claude Code, then run /mcp to check that mission-control is connected and lists its tools.

VS Code

1. Create or edit .vscode/mcp.json in your project root and add the Mission Control MCP server:

.vscode/mcp.json
{
  "servers": {
    "mission-control": {
      "type": "http",
      "url": "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

2. Start the server from mcp.json, then open Copilot Chat in agent mode. Mission Control's tools appear in the tools list.

Cline

Add Mission Control to Cline's MCP server settings:

{
  "mcpServers": {
    "mission-control": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp",
        "--header",
        "Authorization:Bearer <token>"
      ]
    }
  }
}

Continue.dev

Add Mission Control to the mcpServers section of your Continue configuration:

{
  "mcpServers": [
    {
      "name": "mission-control",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp",
        "--header",
        "Authorization:Bearer <token>"
      ]
    }
  ]
}

Direct HTTP

The MCP server uses the MCP HTTP transport: JSON-RPC requests sent with POST to the MCP server URL. There's no other endpoint.

Start a session with an initialize request:

curl -i -X POST https://mc.<org-id>.workload-prod-eu-02.flanksource.com/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    },
    "id": 1
  }'

A successful response is 200 OK, with mission-control as the server name in the result and an Mcp-Session-Id response header. Send that header with every later request of the session, such as tools/list and tools/call.

Troubleshooting

Each step of a connection fails in its own way, so start from the error you see:

Symptom	Cause	Fix
The client can't reach the server	Wrong URL, or a firewall or proxy in the way	Check the MCP server URL, including /mcp or /api/mcp
401 Unauthorized	The client sent no credentials, or the token is wrong, expired or deleted	With OAuth, sign in again from the client. With a token, check the Authorization header, or create a new token
403 forbidden: user <id> does not have mcp:use permission	You don't have mcp:use	Ask an admin for a Role with mcp:use. See Connecting: mcp:use
403 forbidden: the access token's roles don't grant mcp:use	You have mcp:use, but none of the token's Roles allows it	Create a new token and keep the Role that allows mcp:use
A playbook doesn't appear as a tool	You, or the token's Roles, don't have mcp:run on it, or the client connected before the grant	Get mcp:run on the playbook, then reconnect. See Running playbooks: mcp:run
A view doesn't appear as a tool	You, or the token's Roles, can't read the view, or the client connected before the grant	Get read on the view, then reconnect
A tool returns nothing, or fails with forbidden	A permission the tool checks is missing	Find the tool's permission under Reading data. Running a playbook also needs playbook:run and read on its target
A playbook run starts but an action fails with a permission error	The run's actions are checked as the playbook, not as you	Give the playbook what it needs. See Playbooks, notifications and other automation

To see who can use MCP, and which playbooks and views each person or team gets through it, open Settings → MCP. Its pages need access:review.

Next Steps

Once connected, explore the available tools:

• Catalog Tools - Search config items, their changes and relationships
• Connection Tools - List connections
• Playbook Tools - Run playbooks and inspect their runs