Connect an MCP client

1. 1

   Open AI agent access

   In Organization settings, find the MCP token manager. Confirm the active organization and plan before issuing.
2. 2

   Name the owner and purpose

   Use a specific name such as release-agent-production, not default. The name appears in run actor and audit metadata.
3. 3

   Choose access and expiry

   Select Read, Operator, or Operator + secrets, and 1–365 days. The default expiry is 90 days. Grant secrets only when the agent must configure a repository.
4. 4

   Copy once

   Store the rnmcp_… credential in the client’s secret store or environment. Runnable retains only a SHA-256 hash and display prefix.

Codex CLI, IDE extension, and ChatGPT desktop app

These clients share Codex MCP configuration. Put the token in RUNNABLE_MCP_TOKEN, then add the server to ~/.codex/config.toml or a trusted project’s .codex/config.toml.

[mcp_servers.runnable]
url = "https://runnable.cloud/api/mcp"
bearer_token_env_var = "RUNNABLE_MCP_TOKEN"
default_tools_approval_mode = "writes"
tool_timeout_sec = 35

In the desktop app or IDE, open Settings → MCP servers → Add server, choose Streamable HTTP, enter the endpoint, and configure bearer authentication. Restart the client, then use /mcp or the server list to confirm the connection. See the official Codex MCP configuration reference.

URL-and-header JSON clients

For clients whose MCP file accepts a remote URL and static headers, use this shape. Prefer the client’s environment interpolation or secret store over committing the credential.

{
  "mcpServers": {
    "runnable": {
      "url": "https://runnable.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer rnmcp_REPLACE_ME"
      }
    }
  }
}

1. 1

   Find, then inspect

   Use list_runs with a repository/status filter, then get_run. Do not mutate from a list summary alone.
2. 2

   Read the smallest useful log tail

   Start with the failed job’s default 400 lines / 100,000 bytes. Expand only if the failure context is missing.
3. 3

   Choose the correct mutation

   Rerun failed-only for a diagnosed transient result at the same source revision. Dispatch after a newer fix. Cancel only obsolete unfinished work.
4. 4

   Wait without rapid polling

   Call wait_for_run, pass its returned cursor into the next call, and stop when terminal is true.
5. 5

   Inspect the final state

   Call get_run after terminal to capture full job, attempt, and step evidence.

1. 1

   Create a replacement

   Match or narrow the old token’s scope and choose a new expiry. Give the replacement a versioned name.
2. 2

   Update one client

   Replace the secret, restart/reload the MCP client, and verify list_workflows or list_runs.
3. 3

   Update remaining clients

   Use the token’s last-used timestamp and owner inventory to find consumers. Do not share one token across unrelated agents.
4. 4

   Revoke the old token

   Revocation is immediate. An already-revoked token returns not found if revocation is repeated through the customer API.