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 Management: Configure service credentials in addon settings rather than copying them into the bot. Saved secret values cannot be read back.
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	An MCP service you add using 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 gives the bot access to the selected tools and provides the connection settings it needs. Runabot manages the bot’s token.

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#

Use Case#

Runabot normally manages tokens for assigned bots. Use a custom token when you need different expiry or permission settings:

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.

Keep the bot assigned to the addon while using a custom token.

Step-by-Step Procedure#

Assign the Bot to the Addon Profile: Assign the bot to the profile it needs:
```
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: In the MCP Proxy Dashboard under Tokens, locate the bot’s managed token and click Revoke.
Use Revoke, not permanent deletion. Runabot leaves the managed token revoked until you explicitly reassign the profile. The bot’s addon assignment remains in place.
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>
```
Reassigning the profile provides a new managed token.