> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude, ChatGPT, Grok Bot, Cursor, VS Code or Codex to Runtime with one URL, https://mcp.runtm.com/mcp. Copy-paste install for each client, sign-in with OAuth or an API key, and what the server can do. Read before connecting an AI client to Runtime.

The Runtime MCP server lets an AI client create, run and govern your Runtime agents from chat. It calls the same API as the dashboard and the [Agent CLI](https://docs.runtm.com/cloud-api/agent-cli.md), with the same scopes, roles and rate limits.

```text theme={null}
https://mcp.runtm.com/mcp
```

Streamable HTTP. Sign in with OAuth (your Runtime login, including SSO) or send a Runtime API key as a bearer token. See [Authentication](https://docs.runtm.com/mcp/authentication.md).

## Quick start

Pick your client. The first time you use it, it opens a browser to sign in to Runtime.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http runtime https://mcp.runtm.com/mcp
> ```
>
> Then run `/mcp` in Claude Code, pick **runtime** and sign in.

> [tab] Claude.ai / Desktop
>
> 1. Open **Settings → Connectors** and click **Add custom connector**.
> 2. Name it `Runtime`, paste `https://mcp.runtm.com/mcp` and click **Add**.
> 3. Click **Connect** and sign in to Runtime.
>
> Claude Desktop uses the same connectors as Claude.ai. On Team and Enterprise plans, an owner may need to add the connector first.

> [tab] ChatGPT
>
> 1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
> 2. Click **Create**, name it `Runtime`, paste `https://mcp.runtm.com/mcp` and choose **OAuth**.
> 3. Sign in to Runtime when ChatGPT asks.

> [tab] Grok Bot
>
> 1. Send your bot: `Add a custom MCP server called runtime at https://mcp.runtm.com/mcp`.
> 2. Check the name and URL it shows, then confirm.
> 3. Click **Authorize** on the connect card and sign in to Runtime.
>
> Grok Bot connects custom servers with OAuth only, so it always uses sign-in, never an API key.

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "runtime": {
>       "url": "https://mcp.runtm.com/mcp"
>     }
>   }
> }
> ```
>
> Open **Cursor Settings → MCP** and click **Connect** next to **runtime**.

> [tab] VS Code
>
> Add this to `.vscode/mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "runtime": {
>       "type": "http",
>       "url": "https://mcp.runtm.com/mcp"
>     }
>   }
> }
> ```
>
> Click **Start** above the server entry and sign in when VS Code asks.

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add runtime --url https://mcp.runtm.com/mcp
> codex mcp login runtime
> ```

Check it works: ask your client to **call `runtm_whoami`**. It returns your user, organization, role and scopes.

## Use an API key instead

For clients without OAuth, MCP gateways and CI, send a [Runtime API key](https://docs.runtm.com/cloud-api/authentication.md) as a bearer token. The key's scopes decide what the client can do.

```bash Claude Code theme={null}
claude mcp add --transport http runtime https://mcp.runtm.com/mcp \
  --header "Authorization: Bearer $RUNTM_API_KEY"
```

```json Cursor theme={null}
{
  "mcpServers": {
    "runtime": {
      "url": "https://mcp.runtm.com/mcp",
      "headers": { "Authorization": "Bearer ${env:RUNTM_API_KEY}" }
    }
  }
}
```

```json VS Code theme={null}
{
  "inputs": [
    { "type": "promptString", "id": "runtm-api-key", "description": "Runtime API key", "password": true }
  ],
  "servers": {
    "runtime": {
      "type": "http",
      "url": "https://mcp.runtm.com/mcp",
      "headers": { "Authorization": "Bearer ${input:runtm-api-key}" }
    }
  }
}
```

```toml Codex theme={null}
# ~/.codex/config.toml
[mcp_servers.runtime]
url = "https://mcp.runtm.com/mcp"
bearer_token_env_var = "RUNTM_API_KEY"
```

Never paste an API key into a chat. Keep it in the client's config or an environment variable.

## What it can do

| Area | Examples |
| - | - |
| Agents | List the roster and its triggers, create or update an agent, read the scorecard |
| Sessions | Launch a session, send a prompt, follow its events, resolve an approval, run a command |
| Context | Read a template, save a runbook skill, attach skills and MCP servers, rebuild |
| Guardrails | List and save allow, ask and deny rules, hooks and network rules |
| Triggers | Create Slack, GitHub, Linear and Email triggers and schedules, run a schedule once |
| Everything else | Search, describe and call any documented API operation |

31 tools load by default. Add or drop groups with `?toolsets=`. See [Tools](https://docs.runtm.com/mcp/tools.md).

## Safe by design

* **Your permissions, no more.** Every call runs through the REST API with your scopes, org role and rate limits. Tools you can't use are hidden.
* **No credentials in chat.** A step that needs a key, token or password returns a dashboard link for you to finish. A request field named like a credential is refused.
* **Sandbox output is data.** Session events, command output and files are labelled untrusted, and the model is told not to follow instructions in them.
* **A 403 is final.** The model is told to name the missing permission, not to look for another way in.

## Next

> [card] [Authentication](https://docs.runtm.com/mcp/authentication.md)
>
> OAuth, workspaces, scopes and API keys.

> [card] [Tools](https://docs.runtm.com/mcp/tools.md)
>
> Every tool, its inputs and toolsets.

> [card] [Okta](https://docs.runtm.com/mcp/okta.md)
>
> Sign in with Okta, and connect Okta-protected MCP servers to agents.

> [card] [Troubleshooting](https://docs.runtm.com/mcp/troubleshooting.md)
>
> Fix sign-in, 401, 403 and missing tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.