METAL AI
Why this bridge is needed
MCP (Model Context Protocol) is an open-source standard released by Anthropic in November 2024 that standardizes how AI models connect to external data and tools. MCP follows a client-server structure and supports two transport methods: stdio, used for communication between local processes on the same machine, and Streamable HTTP, used for HTTP communication between a remote server and client. However, neither method directly supports the case where the MCP server is local and the MCP client is on a remote cloud.
This gap is especially pronounced for roles such as financial analysts or finance managers, who work primarily with Excel and local files. AWS has internally applied this pattern to a financial AI assistant, which has handled more than 41,000 conversations in the year since its launch, and has now published a simplified version of that internal implementation as a reference architecture.
Architecture: four components
The overall structure consists of four components: the AgentCore runtime, a browser extension, the MCP bridge, and the MCP server. The AgentCore runtime hosts a Strands agent in the cloud and acts as the MCP client, sending tool discovery and invocation requests. The browser extension provides the chat interface while also relaying bidirectionally between the AgentCore runtime (via WebSocket) and the MCP bridge (via native messaging).
The MCP bridge is a FastMCP proxy running on the user's local machine, created by the browser through native messaging host registration. It handles conversion between the native messaging envelope format and MCP JSON-RPC, and uses stdio transport for communication with the MCP server since they are on the same machine. The MCP bridge spawns the MCP server as a child process at startup and keeps it alive until the bridge itself terminates.
Messages originate at the agent and shed one wrapping layer at each hop. The agent sends a JSON envelope in the form {"type": "mcpbridge", "content": ..., "session_id": "..."} over WebSocket to the extension, which forwards it via native messaging to the bridge. The bridge unwraps the envelope and sends the raw JSON-RPC message to the MCP server over stdio. Responses travel back along the reverse path unchanged.
How it works in detail
WebSocket connection and credential protection: At startup, the browser extension sends a pre-sign request to the local bridge, and the bridge uses the user's local AWS credentials together with the Bedrock AgentCore SDK to generate a SigV4-signed wss:// URL. This URL is scoped to the deployed runtime ARN and expires after five minutes. Credentials never leave the user's device or get passed to the browser. If the connection drops, the side panel automatically requests a new URL after two seconds and reconnects, so the expiration window is invisible to the user.
Tool discovery and MCP initialization: The agent calls tools/list for every user message to receive an array of tool schemas. Each schema is wrapped as a Strands AgentTool, and its stream() method sends tools/call requests through the bridge. Adding a tool to the MCP server makes it automatically available starting from the next request, with no agent code changes required. Before tool discovery, the agent performs the standard MCP initialization handshake; tools/list and tools/call requests are only accepted after the initialize request, the server's response, and the notifications/initialized notification exchange are complete.
Inside the MCP bridge: The bridge runs two concurrent loops. The main loop reads messages from the browser, strips the envelope, and places the JSON-RPC content into an input queue. The FastMCP proxy pulls messages from this queue and forwards them to the MCP server subprocess's stdin, while queuing the server's stdout responses into an output queue. A second background loop reads from the output queue, wraps each response in an envelope, and sends it to the browser. This dual-loop design ensures that receiving the next request isn't blocked while a slow tool is being processed.
Getting it running in practice
Deployment is estimated to take about 15 minutes. The prerequisites are as follows.
- AWS: An AWS account with Bedrock model access enabled (the code uses Claude Opus 4.7), IAM permissions for AgentCore, CloudFormation, IAM role creation, and S3, configured AWS CLI credentials, and a completed CDK bootstrap
- Software: Python 3.10 or later, Node.js 20 or later, Google Chrome (with Manifest V3 side panel support), and Git
- Packages to install: AgentCore CLI (
npm install -g @aws/agentcore) and AWS CDK (npm install -g aws-cdk)
The deployment sequence is: clone the GitHub repository (aws-samples/sample-mcp-bridge-agentcore) → install Python dependencies (./scripts/setup.sh) → create and deploy the agent with agentcore create and agentcore deploy → enter the runtime ARN and region into bridge/bridge_config.json → load the Chrome extension → register the native messaging bridge with ./manifests/install.sh <extension-id>.
Adding a new MCP server is as simple as adding one line to mcp.json. The bridge handles the rest of the connection work.
Cost: The AgentCore runtime is billed per invocation with no idle cost, and Bedrock model usage is billed at Claude's standard per-token rates. The bridge, extension, and MCP server all run locally, so there is no additional cost. Specific unit pricing was not disclosed in the source.
Security considerations and limitations
The current sample implementation applies three security measures: origin restriction, where Chrome only allows connections from the extension ID specified in the native messaging manifest's allowed_origins; SigV4-signed pre-signed URLs that expire after five minutes; and process isolation, where the extension, bridge, and MCP server each run in separate OS processes with no shared memory.
AWS recommends additional measures for production environments: an authentication layer using a JWT handshake (via Amazon Cognito or similar) to block unauthorized use, signing of MCP message payloads using Ed25519, restricting file system scope with an allow-list of directories the MCP server can access, and audit logging that records the name, arguments, timestamp, and result status of every tool call to a local file. The key exposure point in this architecture is the bridge itself, which runs locally under the user's file system permissions while taking instructions from the cloud agent.
The current sample's native message size limits are a maximum of 1 MB in the native-messaging-host-to-browser direction and up to 64 MiB in the browser-to-native-messaging-host direction. For production deployment, AWS recommends packaging the bridge as a standalone executable binary using PyInstaller so it can run without a Python environment.
