MCP Proxy Addon#

The MCP Proxy addon is a secure gateway and mediation layer for Model Context Protocol (MCP) servers in Runabot. It allows AI agents, developer workspaces, and autonomous bots (such as OpenClaw, Codex, Claude Code, or VS Code) to interact with external tools and APIs without holding sensitive third-party credentials directly in the workload environment.

Why MCP Proxy?#

In an AI agent environment, granting agents direct access to raw API keys or unrestricted network endpoints introduces serious security risks. MCP Proxy solves this by enforcing a zero-trust model:

Credential Isolation: Upstream API keys and authorization tokens are stored exclusively inside MCP Proxy as write-only secrets. The bot runtime only receives a scoped proxy token.
Tool Governance: Tools exposed by upstream servers are discovered and can be approved, quarantined, or blocked before any agent can execute them.
Fine-Grained Access Profiles: Tools can be grouped into role-specific profiles (e.g. read-only-docs, github-issue-reviewer, database-analytics), limiting what each bot can invoke.
Auditing and Rate Limiting: All tool calls flow through the proxy, providing visibility and control over agent activities.

Core Concepts#

Concept	Description
Upstream	A backend MCP server connected to the proxy via standard protocols: Stdio, Server-Sent Events (SSE), HTTP, or Streamable HTTP.
Tool Approval	Discovered tools must be explicitly approved or assigned before agents can execute them. Discovered tools can be quarantined if they exhibit unexpected changes.
Write-Only Secrets	Sensitive headers or environment variables used by upstreams. Secret values can be written or deleted, but are never exposed back in read operations.
Access Profile	A policy set that binds specific upstreams and approved tools together.
Managed Bot Token	A non-expiring proxy token automatically provisioned when a bot workload is assigned to an MCP Proxy access profile.
Custom Token	A user-created proxy token with custom permissions, allowed upstreams, or finite lifespans (e.g. 7 days, 30 days).

Getting Started#

1. Accessing the MCP Proxy Dashboard#

Every installed MCP Proxy addon instance provides a web dashboard protected by Runabot Single Sign-On (SSO). You can access it directly from the Runabot web interface by navigating to Addons → MCP Proxy → Open Dashboard.

Alternatively, you can manage the instance using the Runabot CLI:

runabot addon mcpproxy upstream list <addon-name>

2. Registering an Upstream Server#

To connect an upstream MCP server, configure it via the web dashboard or with the CLI:

runabot addon mcpproxy upstream create <addon-name> documentation \
  --protocol streamable-http \
  --url https://mcp.docs.example.com/mcp

3. Reviewing and Approving Tools#

Once connected, MCP Proxy automatically discovers available tools:

# List discovered tools
runabot addon mcpproxy tool list <addon-name> documentation

# Approve a specific tool
runabot addon mcpproxy tool approve <addon-name> documentation search_docs

4. Creating an Access Profile#

Access profiles group tools into reusable permissions:

runabot addon mcpproxy profile create <addon-name> researcher \
  --upstream documentation \
  --tool documentation=search_docs

5. Assigning the Profile to a Bot#

Assigning an access profile to a bot automatically:

Opens the network firewall so the bot container can reach the MCP Proxy addon.
Generates a permanent managed token (runabot-<bot-id>).
Injects the addon endpoint URL and token into the bot workload environment.

runabot addon mcpproxy assign <addon-name> researcher <bot-id>

Verify the bot’s effective access at any time:

runabot addon mcpproxy access effective <addon-name> <bot-id>

Configuring Coding Agents in Bot Workloads#

Inside your bot workload (such as a Linux workload running Codex or Claude Code), you can configure the MCP client to connect to the MCP Proxy instance.

Example: Codex Configuration#

In ~/.codex/config.toml:

[mcp_servers.<addon-name>]
url = "https://<addon-name>-mcp-proxy.<domain>/mcp"
http_headers = { Authorization = "Bearer <token>" }

By default, the managed token and endpoint URL are exported into /root/linux.env inside the bot container as <addon_name>_api_key and <addon_name>_url.

Using Custom Access Tokens (Opt-Out Workaround)#

Use Case#

By default, Runabot automatically reconciles and maintains a permanent managed token (runabot-<bot-id>) for each assigned bot. However, certain security policies or workflows require custom token characteristics:

Finite Expiration & Rotation: Enforcing a strict token expiry (e.g. 7 or 30 days) with scheduled credential rotation.
Dedicated Scoping: Restricting an agent to a subset of permissions (e.g. read-only) independent of profile synchronizations.
Developer-Specific Credentials: Using individual tokens for testing tools or running sandboxed evaluation tasks.

Because the bot requires network firewall authorization to communicate with the addon, you must keep the bot assigned to the addon while overriding the credential.

Step-by-Step Procedure#

Assign the Bot to the Addon Profile: Ensure the bot is assigned to the profile so that the network firewall permits traffic:
```
runabot addon mcpproxy assign <addon-name> <profile-name> <bot-id>
```
Generate a Custom Scoped Token: In the MCP Proxy Web Dashboard, go to Tokens → Create Token, or run:
```
runabot addon mcpproxy token create <addon-name> custom-team-token \
  --upstream documentation \
  --permission read \
  --expires-in 30d
```
Save the returned token secret securely (it is revealed only once).
Revoke the Managed Token (Soft-Revoke): In the MCP Proxy Dashboard under Tokens, locate the managed token (runabot-<bot-id>) and click Revoke (or delete it using the soft-revoke action).
Do NOT use permanent deletion (/permanent). Perform a standard soft-revocation.
When a managed token has revoked: true, the Runabot reconciler recognizes this as an intentional user opt-out. It will not recreate, repair, or regenerate the managed token, and it leaves the revoked tombstone in place. The network firewall between the bot and the addon remains open.
Configure the Agent with the Custom Token: Update your bot’s agent configuration (such as ~/.codex/config.toml or custom environment variables) to use the custom token:
```
[mcp_servers.<addon-name>]
url = "https://<addon-name>-mcp-proxy.<domain>/mcp"
http_headers = { Authorization = "Bearer mcp_agt_your_custom_token..." }
```
Re-enabling Automated Managed Tokens: If you ever want to revert to automatic managed token provisioning, re-assign the bot profile via Runabot:
```
runabot addon mcpproxy assign <addon-name> <profile-name> <bot-id>
```
This orchestrator action clears the opt-out state and provisions a fresh permanent managed token.