MCP Hub

Overview

MCP Hub lets your agents call tools on any MCP (Model Context Protocol) server through a single, secure endpoint. Your real credentials stay on Runloop’s servers — the agent only gets opaque, per-server tokens scoped to the tools you allow. Configure multiple MCP servers, and your agent registers each one using the shared endpoint URL and its dedicated token.

Why Use MCP Hub?

Single Endpoint, Per-Server Tokens

Instead of configuring your agent to connect to each MCP server’s real endpoint individually, MCP Hub proxies them all through one URL ($RL_MCP_URL). Each MCP server gets its own opaque token delivered via a named environment variable (e.g., $GITHUB_MCP_SECRET, $SLACK_MCP_SECRET), so you can register each server separately with fine-grained control.

Credential Isolation

Your MCP server credentials (GitHub PATs, Slack tokens, etc.) never enter the devbox. The agent only sees:

A shared gateway URL ($RL_MCP_URL)
Per-server opaque tokens (e.g., $GITHUB_MCP_SECRET, $SLACK_MCP_SECRET)

Even if an attacker gains full access to the devbox, they cannot extract your actual API credentials.

Tool-Level Access Control

MCP configs let you specify exactly which tools an agent can use, using glob patterns:

["*"] — all tools from the server
["github.search_*", "github.get_*"] — only read operations
["slack.post_message"] — a single specific tool

Tools that don’t match the allowed patterns are invisible to the agent — they won’t appear in tools/list and calls to them are rejected.

Quickstart

Claude Code Agent
Claude API with MCP

Run Claude Code as an autonomous agent inside a devbox with MCP tools — orchestrated entirely from your application code.

Create an MCP config and secret

Register the GitHub MCP server, choose which tools to expose, and store your GitHub PAT as a Runloop secret. The credential is stored server-side — the devbox never sees it.

from runloop_api_client import RunloopSDK

sdk = RunloopSDK()

mcp_config = sdk.mcp_config.create(
    name="github-example",
    endpoint="https://api.githubcopilot.com/mcp/",
    allowed_tools=["*"],
    description="GitHub MCP server",
)

sdk.api.secrets.create(name="GITHUB_MCP_TOKEN", value="ghp_abc123...")

import { RunloopSDK } from "@runloop/api-client";

const sdk = new RunloopSDK();

const mcpConfig = await sdk.mcpConfig.create({
    name: "github-example",
    endpoint: "https://api.githubcopilot.com/mcp/",
    allowed_tools: ["*"],
    description: "GitHub MCP server",
});

await sdk.api.secrets.create({ name: "GITHUB_MCP_TOKEN", value: "ghp_abc123..." });

Launch a devbox with MCP Hub

The devbox receives $RL_MCP_URL (the shared proxy endpoint) and a per-server token environment variable — not the raw GitHub token. The map key (GITHUB_MCP_SECRET) becomes the environment variable name for that server’s opaque token.

devbox = sdk.devbox.create(
    name="mcp-claude-code",
    launch_parameters={
        "resource_size_request": "SMALL",
        "keep_alive_time_seconds": 300,
    },
    mcp={"GITHUB_MCP_SECRET": {"mcp_config": mcp_config.id, "secret": "GITHUB_MCP_TOKEN"}},
)

const devbox = await sdk.devbox.create({
    name: "mcp-claude-code",
    launch_parameters: {
        resource_size_request: "SMALL",
        keep_alive_time_seconds: 300,
    },
    mcp: { GITHUB_MCP_SECRET: { mcp_config: mcpConfig.id, secret: "GITHUB_MCP_TOKEN" } },
});

Install Claude Code and register MCP Hub

Install Claude Code inside the devbox, then register each MCP server using its own token environment variable.

devbox.cmd.exec("npm install -g @anthropic-ai/claude-code")

devbox.cmd.exec(
    'claude mcp add github-mcp --transport http "$RL_MCP_URL" '
    '--header "Authorization: Bearer $GITHUB_MCP_SECRET"'
)

await devbox.cmd.exec("npm install -g @anthropic-ai/claude-code");

await devbox.cmd.exec(
    'claude mcp add github-mcp --transport http "$RL_MCP_URL" '
    + '--header "Authorization: Bearer $GITHUB_MCP_SECRET"'
);

Run a prompt with MCP tools

Claude Code automatically discovers the MCP tools and uses them to answer the prompt.

result = devbox.cmd.exec(
    f"ANTHROPIC_API_KEY={anthropic_key} claude -p "
    '"Use the MCP tools to get my last PR and describe what it does." '
    "--dangerously-skip-permissions"
)
print(result.stdout())

const result = await devbox.cmd.exec(
    `ANTHROPIC_API_KEY=${anthropicKey} claude -p `
    + `"Use the MCP tools to get my last PR and describe what it does." `
    + `--dangerously-skip-permissions`
);
console.log((await result.stdout()).trim());

See the full runnable examples: Python · TypeScript

Use the Anthropic API’s mcp_servers parameter to give Claude direct access to MCP tools — no agent framework needed.

Create an MCP config, secret, and devbox

Set up the MCP config, store your GitHub PAT, and launch a devbox with MCP Hub. The devbox receives $RL_MCP_URL (shared endpoint) and $GITHUB_MCP_SECRET (per-server token).

from runloop_api_client import RunloopSDK

sdk = RunloopSDK()

mcp_config = sdk.mcp_config.create(
    name="github-example",
    endpoint="https://api.githubcopilot.com/mcp/",
    allowed_tools=["*"],
)

sdk.api.secrets.create(name="GITHUB_MCP_TOKEN", value="ghp_abc123...")

devbox = sdk.devbox.create(
    name="mcp-claude-api",
    mcp={"GITHUB_MCP_SECRET": {"mcp_config": mcp_config.id, "secret": "GITHUB_MCP_TOKEN"}},
)

import { RunloopSDK } from "@runloop/api-client";

const sdk = new RunloopSDK();

const mcpConfig = await sdk.mcpConfig.create({
    name: "github-example",
    endpoint: "https://api.githubcopilot.com/mcp/",
    allowed_tools: ["*"],
});

await sdk.api.secrets.create({ name: "GITHUB_MCP_TOKEN", value: "ghp_abc123..." });

const devbox = await sdk.devbox.create({
    name: "mcp-claude-api",
    mcp: { GITHUB_MCP_SECRET: { mcp_config: mcpConfig.id, secret: "GITHUB_MCP_TOKEN" } },
});

Call the Anthropic API with MCP servers

Pass the MCP Hub endpoint to the Anthropic SDK’s mcp_servers parameter, registering each MCP server with its own token. Claude automatically discovers and calls the tools — no manual tool definitions needed.

import anthropic

anthropic_client = anthropic.Anthropic()

mcp_url = devbox.cmd.exec("echo $RL_MCP_URL").stdout().strip()
github_token = devbox.cmd.exec("echo $GITHUB_MCP_SECRET").stdout().strip()

response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": mcp_url,
            "authorization_token": github_token,
        }
    ],
    messages=[{
        "role": "user",
        "content": "Search for authentication bugs in runloopai/demo"
    }],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "mcp_tool_result":
        print(f"Tool result from: {block.server_label}")

import Anthropic from "@anthropic-ai/sdk";

const anthropicClient = new Anthropic();

const mcpUrl = (await devbox.cmd.exec("echo $RL_MCP_URL")).stdout().trim();
const githubToken = (await devbox.cmd.exec("echo $GITHUB_MCP_SECRET")).stdout().trim();

const response = await anthropicClient.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    mcp_servers: [
        {
            type: "url",
            url: mcpUrl,
            authorization_token: githubToken,
        }
    ],
    messages: [{
        role: "user",
        content: "Search for authentication bugs in runloopai/demo"
    }],
});

for (const block of response.content) {
    if (block.type === "text") {
        console.log(block.text);
    } else if (block.type === "mcp_tool_result") {
        console.log(`Tool result from: ${block.server_label}`);
    }
}

Your code never sees your real GitHub PAT, Slack token, or any other credential — only opaque per-server tokens like $GITHUB_MCP_SECRET or $SLACK_MCP_SECRET. This protects your credentials from:

Prompt injection attacks — Even if an attacker tricks your agent into printing environment variables, they only get useless opaque tokens
Malicious code — Code running in the devbox cannot access your actual API credentials
Scoped access — Each MCP server gets its own token, so you can grant and revoke access per server independently

Combine MCP Hub with Network Policies to further lock down the devbox. Set allow_mcp_gateway=True on a restrictive policy to allow MCP Hub traffic while blocking all other unauthorized outbound requests.

How It Works

Configure MCP Configs: Define which MCP servers to connect to and which tools are allowed
Store Secrets: Create account secrets containing the credentials for each MCP server
Launch with MCP: Create a devbox with your MCP configs — it receives $RL_MCP_URL (shared endpoint) and a per-server token environment variable for each MCP server
Register Each Server: Your agent registers each MCP server using the shared URL and its per-server token

MCP Config Options

Option	Description	Required
`name`	Unique name for the MCP config	Yes
`endpoint`	Target MCP server URL	Yes
`allowed_tools`	Glob patterns for permitted tools (e.g., `[""]`, `["github.search_"]`)	Yes
`description`	Optional description	No

Tool Access Patterns

MCP configs use glob patterns to control which tools are exposed to the agent:

Pattern	Matches	Use Case
`*`	All tools	Full access
`github.search_*`	`github.search_code`, `github.search_issues`, etc.	Read-only search
`github.get_*`	`github.get_repo`, `github.get_issue`, etc.	Read-only data retrieval
`slack.post_message`	Only `slack.post_message`	Single specific tool

Tools that don’t match your allowed patterns are completely hidden — they won’t appear when the agent lists tools, and any attempt to call them is rejected.

Multiple MCP Servers

You can configure multiple MCP servers for a single devbox. Each server gets its own token environment variable, and all share the same $RL_MCP_URL endpoint.

github_config = await runloop.mcp_config.create(
    name="github-readonly",
    endpoint="https://api.githubcopilot.com/mcp/",
    allowed_tools=["github.search_*", "github.get_*"]
)

slack_config = await runloop.mcp_config.create(
    name="slack-notify",
    endpoint="https://slack-mcp.example.com",
    allowed_tools=["slack.post_message"]
)

devbox = await runloop.devbox.create(
    name="multi-mcp-agent",
    mcp={
        "GITHUB_MCP_SECRET": {"mcp_config": github_config.id, "secret": "GITHUB_MCP_TOKEN"},
        "SLACK_MCP_SECRET": {"mcp_config": slack_config.id, "secret": "SLACK_MCP_TOKEN"},
    }
)

# The devbox receives:
#   $RL_MCP_URL     — shared endpoint
#   $GITHUB_MCP_SECRET  — opaque token for GitHub tools
#   $SLACK_MCP_SECRET   — opaque token for Slack tools

const githubConfig = await runloop.mcpConfig.create({
    name: "github-readonly",
    endpoint: "https://api.githubcopilot.com/mcp/",
    allowed_tools: ["github.search_*", "github.get_*"]
});

const slackConfig = await runloop.mcpConfig.create({
    name: "slack-notify",
    endpoint: "https://slack-mcp.example.com",
    allowed_tools: ["slack.post_message"]
});

const devbox = await runloop.devbox.create({
    name: "multi-mcp-agent",
    mcp: {
        GITHUB_MCP_SECRET: { mcp_config: githubConfig.id, secret: "GITHUB_MCP_TOKEN" },
        SLACK_MCP_SECRET: { mcp_config: slackConfig.id, secret: "SLACK_MCP_TOKEN" },
    }
});

// The devbox receives:
//   $RL_MCP_URL     — shared endpoint
//   $GITHUB_MCP_SECRET  — opaque token for GitHub tools
//   $SLACK_MCP_SECRET   — opaque token for Slack tools

claude mcp add github-mcp --transport http "$RL_MCP_URL" --header "Authorization: Bearer $GITHUB_MCP_SECRET"
claude mcp add slack-mcp  --transport http "$RL_MCP_URL" --header "Authorization: Bearer $SLACK_MCP_SECRET"

MCP Hub routes each tool call to the correct upstream server, so the agent doesn’t need to know which server hosts which tool.

Managing MCP Configs

List MCP Configs

configs = await runloop.mcp_config.list()
for config in configs:
    print(f"{config.name}: {config.endpoint}")

const configs = await runloop.mcpConfig.list();
for (const config of configs) {
    console.log(`${config.name}: ${config.endpoint}`);
}

Update an MCP Config

mcp_config = runloop.mcp_config.from_id("mcp_1234567890")
updated = await mcp_config.update(
    allowed_tools=["github.*"],
    description="Expanded GitHub access"
)

const mcpConfig = runloop.mcpConfig.fromId("mcp_1234567890");
const updated = await mcpConfig.update({
    allowed_tools: ["github.*"],
    description: "Expanded GitHub access"
});

Delete an MCP Config

mcp_config = runloop.mcp_config.from_id("mcp_1234567890")
await mcp_config.delete()

const mcpConfig = runloop.mcpConfig.fromId("mcp_1234567890");
await mcpConfig.delete();

Deleting an MCP config is permanent and cannot be undone. Ensure no devboxes are actively using the config before deletion.

Security Best Practices

1. Use Minimal Tool Permissions

Start with the narrowest set of tools your agent actually needs, and expand only as required.

✅ ["github.search_code", "github.get_issue"] — specific tools
⚠️ ["github.*"] — all tools from one server
❌ ["*"] — all tools (use only for development/testing)

2. Separate Configs by Permission Level

Create distinct MCP configs for different access levels rather than one permissive config:

github-research   → ["github.search_*", "github.get_*"]   (read-only)
github-contributor → ["github.*"]                          (read + write)

3. Use Descriptive Config Names

Choose clear names that describe the access level and purpose:

✅ github-readonly, slack-notify-only, jira-read-write
❌ config1, test, my-mcp

Multi-Tenant Pattern

MCP configs define the access policy, while secrets provide credentials. Reuse the same config with different secrets for each tenant:

devbox_a = await runloop.devbox.create(
    mcp={"GITHUB_MCP_SECRET": {"mcp_config": "github-readonly", "secret": "TENANT_A_GITHUB_TOKEN"}}
)

devbox_b = await runloop.devbox.create(
    mcp={"GITHUB_MCP_SECRET": {"mcp_config": "github-readonly", "secret": "TENANT_B_GITHUB_TOKEN"}}
)

const devboxA = await runloop.devbox.create({
    mcp: { GITHUB_MCP_SECRET: { mcp_config: "github-readonly", secret: "TENANT_A_GITHUB_TOKEN" } }
});

const devboxB = await runloop.devbox.create({
    mcp: { GITHUB_MCP_SECRET: { mcp_config: "github-readonly", secret: "TENANT_B_GITHUB_TOKEN" } }
});

Comparison: MCP Hub vs Agent Gateways

Feature	MCP Hub	Agent Gateways
Protocol	MCP (Model Context Protocol)	HTTP REST APIs
Use case	Tool-based agent capabilities (code search, issue management, etc.)	LLM API access (Anthropic, OpenAI, etc.)
Access control	Tool-level with glob patterns	Endpoint-level
Aggregation	Multiple MCP servers → single endpoint, per-server tokens	One API per gateway
Environment vars	`$RL_MCP_URL` (shared), `$<NAME>` (per server)	`$NAME_URL`, `$NAME`

Use MCP Hub when your agent needs to use MCP tool servers. Use Agent Gateways when your agent needs to call LLM REST APIs.

Account Secrets — Managing secrets for your account
Agent Gateways — Securely proxy API requests
Network Policies — Controlling network access for devboxes
Agents API — Building AI agents with Runloop

Overview

Tools

Components

Benchmarks & Evals

Debugging

Overview

Why Use MCP Hub?

Single Endpoint, Per-Server Tokens

Credential Isolation

Tool-Level Access Control

Quickstart

How It Works

MCP Config Options

Tool Access Patterns

Multiple MCP Servers

Managing MCP Configs

List MCP Configs

Update an MCP Config

Delete an MCP Config

Security Best Practices

1. Use Minimal Tool Permissions

2. Separate Configs by Permission Level

3. Use Descriptive Config Names

Multi-Tenant Pattern

Comparison: MCP Hub vs Agent Gateways

​Overview

​Why Use MCP Hub?

​Single Endpoint, Per-Server Tokens

​Credential Isolation

​Tool-Level Access Control

​Quickstart

​How It Works

​MCP Config Options

​Tool Access Patterns

​Multiple MCP Servers

​Managing MCP Configs

​List MCP Configs

​Update an MCP Config

​Delete an MCP Config

​Security Best Practices

​1. Use Minimal Tool Permissions

​2. Separate Configs by Permission Level

​3. Use Descriptive Config Names

​Multi-Tenant Pattern

​Comparison: MCP Hub vs Agent Gateways

​Related Documentation

Overview

Why Use MCP Hub?

Single Endpoint, Per-Server Tokens

Credential Isolation

Tool-Level Access Control

Quickstart

How It Works

MCP Config Options

Tool Access Patterns

Multiple MCP Servers

Managing MCP Configs

List MCP Configs

Update an MCP Config

Delete an MCP Config

Security Best Practices

1. Use Minimal Tool Permissions

2. Separate Configs by Permission Level

3. Use Descriptive Config Names

Multi-Tenant Pattern

Comparison: MCP Hub vs Agent Gateways

Related Documentation