AgentWorks documentation

🌉 MCP Bridge Layer & Exposed APIs

The MCP Bridge Layer is a critical architectural component of Runloop. It acts as a universal proxy and translation layer, allowing external local CLI agents (like Claude Code and Gemini CLI) to seamlessly access the orchestrator's entire suite of loaded tools, virtual tools, and workspace capabilities.

Architecture Overview

Instead of requiring every agent to manage its own MCP server connections, the orchestrator centralizes tool discovery, session management, and routing. External agents use a lightweight proxy binary called mcpbridge to communicate with the orchestrator's REST API.

1. Local CLI Agent (e.g., claude-code, gemini) spawns mcpbridge.
2. mcpbridge translates the stdio-based MCP protocol into HTTP REST calls.
3. Orchestrator processes the HTTP request, executes the tool (routing to Docker, external APIs, or the local Workspace), and returns the result.

🔌 Exposed APIs

The orchestrator exposes several API layers to facilitate this bridge and manage the workspace.

1. Tool Execution & Discovery (Bridge API)

These endpoints are consumed by mcpbridge and the web UI to interact with tools.

• POST /api/mcp/execute
  • The central routing endpoint. Accepts a JSON payload containing the server_name, tool_name, and arguments.
  • Automatically routes the request to the correct underlying MCP server, virtual tool, or workspace capability.
• GET /api/tools
  • Returns a flattened, formatted schema of all available tools across all connected MCP servers and virtual tools.
• GET /api/mcp-config & POST /api/mcp-config
  • Retrieves and updates the active MCP server configuration (mcp_servers.json).
• POST /api/mcp-config/discover
  • Forces a manual discovery and reconnection to all configured MCP servers.

2. Workspace API (Port 8080)

The workspace container runs a dedicated Planner API that the orchestrator interfaces with for local file and system management.

• Document Management:
  • GET /api/documents / POST /api/documents
  • GET/PUT/DELETE /api/documents/*filepath
  • GET /api/glob (File discovery via glob patterns)
• Search & Semantic Intelligence:
  • GET /api/search (Lexical grep search)
  • POST /api/search/process-file
• System & Execution:
  • POST /api/execute (Secure shell command execution within the workspace)
  • POST /api/upload (File uploads)

🌎 Universal Stdio Gateway

The mcpbridge binary isn't just for Claude or Gemini—it serves as a Universal Stdio Gateway.

Any external LLM agent, framework (LangChain, AutoGPT, CrewAI), or custom script that supports the Model Context Protocol (MCP) via stdio can use mcpbridge to access your entire tool ecosystem through a single connection.

Why use the Centralized Bridge?

• Single Connection, 100+ Tools: Connect to one "server" (mcpbridge) and immediately gain access to every tool configured in your orchestrator (Slack, Workspace, Browser, etc.).
• Centralized Auth: Manage API keys and OAuth tokens in one place (the orchestrator) rather than in every individual agent script.
• Session Isolation: Use the MCP_SESSION_ID environment variable to isolate tool execution and folder guards between different external agents.
• Monitoring: Every tool call made via the bridge is logged and visible in the orchestrator's central dashboard.

Configuration for External Frameworks

To connect an external agent, simply point it to the mcpbridge binary:

# Example: Launching a custom MCP-compatible agent
my-agent-cli --mcp-command "mcpbridge" --mcp-env "MCP_API_URL=http://localhost:8080/api"