From IDE to Cloud: Lifting Your Local Agent into an MCP Server on Amazon Bedrock AgentCore

You have built an AI agent that works beautifully on your laptop. It calls tools, reasons through problems, and returns exactly the answer your users need. There is just one problem: it lives on localhost.

Moving from a local prototype to a production-grade, multi-tenant cloud service usually means weeks of infrastructure work — containers, load balancers, session isolation, authentication, observability. Amazon Bedrock AgentCore Runtime collapses that effort into a handful of commands while the Model Context Protocol (MCP) gives your agent a standard interface that any MCP-compatible client can discover and invoke.

In this post you will take a Python agent running in your IDE, transform it into an MCP server, and deploy it to AgentCore Runtime — with working code at every step.

---

What Is Amazon Bedrock AgentCore Runtime?

Amazon Bedrock AgentCore Runtime is a serverless hosting environment purpose-built for AI agents. It provides several capabilities that are hard to replicate on your own:

• Framework-agnostic — Works with Strands Agents, LangGraph, CrewAI, or any custom Python agent. You are not locked into a single orchestration framework.
• Model flexibility — Use any LLM — Amazon Bedrock models, Anthropic Claude, Google Gemini, or OpenAI.
• Session isolation — Each user session runs in a dedicated microVM with isolated CPU, memory, and filesystem. When the session ends, the microVM is terminated and memory is sanitised.
• Protocol support — Native support for Model Context Protocol (MCP) and Agent-to-Agent (A2A) communication.
• Extended execution — Synchronous requests get a 15-minute timeout; asynchronous sessions can run for up to 8 hours.
• Consumption-based pricing — You pay only for the compute your agent actually uses, not for idle time waiting on LLM responses.

In short, AgentCore Runtime handles the infrastructure so you can focus on the agent logic.

---

What Is MCP and Why Does It Matter?

The Model Context Protocol (MCP) is an open standard that defines how AI agents discover and invoke tools over HTTP. Think of it as a contract: an MCP server exposes tools with typed inputs and outputs, and any MCP client can discover those tools at runtime and call them without custom integration code.

Key characteristics of MCP on AgentCore Runtime:

• Stateless streamable-HTTP — AgentCore requires stateless servers. The platform automatically injects a Mcp-Session-Id header for session continuity.
• Tool discovery — Clients call list_tools() to discover every tool the server exposes, with full JSON Schema descriptions.
• Standard path — The server listens on 0.0.0.0:8000/mcp, which is the default path supported by most MCP SDKs.
• Interoperability — Any MCP client — Claude Code, Cursor, Kiro, Amazon Q CLI — can connect to your deployed server with zero custom wiring.

By implementing MCP, your agent becomes a reusable building block that other agents and developer tools can compose into larger systems.

---

Architecture Overview

The flow has four stages: build locally and test on localhost, transform for AgentCore compatibility, deploy to AWS via the AgentCore CLI, and invoke from any MCP client.

 LOCAL IDE                    TRANSFORMATION                AGENTCORE RUNTIME                 INVOCATION
 ─────────                    ──────────────                ─────────────────                 ──────────

 ┌─────────────────────┐      ┌──────────────────────┐      ┌──────────────────────────┐      ┌─────────────────────┐
 │                     │      │                      │      │                          │      │  Claude Code /      │
 │  MCP Server Code    │      │  Install AgentCore   │      │  agentcore configure     │      │  Cursor / Kiro      │
 │  my_mcp_server.py   │      │  MCP Server in IDE   │      │  --protocol MCP          │      │         │           │
 │         │           │      │         │            │      │         │                │      │         ▼           │
 │         ▼           │      │         ▼            │      │         ▼                │      │  ┌───────────────┐  │
 │  Local Test         │─────▶│  Transform Agent     │─────▶│  agentcore launch        │      │  │ Agent Runtime │  │
 │  localhost:8000/mcp │      │  + BedrockAgentCore  │      │  Build + ECR + Deploy    │      │  │     ARN       │◀─┤
 │                     │      │  App wrapper         │      │         │                │      │  │  MicroVM      │  │
 └─────────────────────┘      └──────────────────────┘      │         ▼                │      │  │  Isolation    │  │
                                                            │  ┌────────────────────┐  │      │  └───────────────┘  │
                                                            │  │  Agent Runtime ARN │  │      │         ▲           │
                                                            │  │  MicroVM Isolation  │──┼─────▶│  Remote MCP Client │
                                                            │  │  Session Mgmt      │  │      │  Python Script      │
                                                            │  └────────────────────┘  │      │         ▲           │
                                                            │                          │      │  MCP Inspector      │
                                                            └──────────────────────────┘      └─────────────────────┘

---

Prerequisites

Before you start, make sure you have:

• An AWS account with Amazon Bedrock AgentCore permissions
• AWS CLI installed and configured with appropriate credentials
• Python 3.10+ installed (3.13 recommended)
• uv package manager installed (optional but recommended)
• An MCP client: Claude Code, Cursor, Kiro, or Amazon Q CLI

Install the core packages:

pip install mcp
pip install bedrock-agentcore
pip install bedrock-agentcore-starter-toolkit

---

Step 1: Build Your Local MCP Server

Start by creating a simple MCP server with a few tools. This is the agent you will later lift into AgentCore Runtime.

Create a file called my_mcp_server.py:

# my_mcp_server.py

from mcp.server.fastmcp import FastMCP
from starlette.responses import JSONResponse

# Create the MCP server instance
# host must be 0.0.0.0 for AgentCore compatibility
mcp = FastMCP(host="0.0.0.0", stateless_http=True)


@mcp.tool()
def summarise_architecture(service_name: str) -> str:
    """Summarise the high-level architecture of an AWS service."""
    return (
        f"The {service_name} architecture typically includes "
        f"a control plane for management operations and a data plane "
        f"for runtime request handling, with IAM for access control."
    )


@mcp.tool()
def estimate_monthly_cost(
    service: str, requests_per_month: int, avg_duration_ms: int
) -> str:
    """Estimate monthly cost for a serverless AWS service."""
    cost_per_request = 0.0000002
    cost_per_gb_second = 0.0000166667
    memory_gb = 0.5
    duration_seconds = avg_duration_ms / 1000
    compute_cost = requests_per_month * duration_seconds * memory_gb * cost_per_gb_second
    request_cost = requests_per_month * cost_per_request
    total = compute_cost + request_cost
    return f"Estimated monthly cost for {service}: ${total:,.2f}"


@mcp.tool()
def generate_iam_policy(actions: list[str], resource_arn: str) -> dict:
    """Generate a least-privilege IAM policy document."""
    return {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": actions,
                "Resource": resource_arn,
            }
        ],
    }


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

This server exposes three tools: an architecture summariser, a cost estimator, and an IAM policy generator. The key details for AgentCore compatibility are host="0.0.0.0" and stateless_http=True.

Test Locally

Start the server:

python my_mcp_server.py

The server starts on port 8000. From a separate terminal, run a test client:

# my_mcp_client.py

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main():
    mcp_url = "http://localhost:8000/mcp"

    async with streamablehttp_client(
        mcp_url, headers={}, timeout=120, terminate_on_close=False
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # Discover tools
            tools = await session.list_tools()
            print("Available tools:")
            for tool in tools.tools:
                print(f"  - {tool.name}: {tool.description}")

            # Invoke a tool
            result = await session.call_tool(
                "estimate_monthly_cost",
                {
                    "service": "AWS Lambda",
                    "requests_per_month": 1_000_000,
                    "avg_duration_ms": 200,
                },
            )
            print(f"\nResult: {result.content[0].text}")


asyncio.run(main())

You should see your three tools listed and a cost estimate returned.

---

Step 2: Install the AgentCore MCP Server in Your IDE

AWS provides an MCP server specifically for AgentCore development. This server runs inside your IDE's MCP client and guides the transformation, deployment, and testing workflow conversationally.

Add the following to your MCP client configuration:

Claude Code (~/.claude/mcp.json)

{
  "mcpServers": {
    "bedrock-agentcore-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.amazon-bedrock-agentcore-mcp-server@latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": [
        "search_agentcore_docs",
        "fetch_agentcore_doc"
      ]
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "bedrock-agentcore-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.amazon-bedrock-agentcore-mcp-server@latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": [
        "search_agentcore_docs",
        "fetch_agentcore_doc"
      ]
    }
  }
}

Restart your MCP client after adding the configuration. Verify by checking that search_agentcore_docs and fetch_agentcore_doc tools appear in your tool list.

---

Step 3: Transform Your Agent for AgentCore

If you are deploying an MCP server (not a general agent), the transformation is minimal. Your FastMCP server already meets the protocol contract — it listens on 0.0.0.0:8000/mcp with stateless streamable-HTTP transport.

However, if you are deploying a general agent (not an MCP server), you need to wrap it with the AgentCore SDK:

1. Add the AgentCore import

from bedrock_agentcore.runtime import BedrockAgentCoreApp

2. Initialise the application

app = BedrockAgentCoreApp()

3. Decorate your entrypoint

@app.entrypoint
def handler(event, context):
    user_prompt = event.get("prompt", "")
    response = my_agent.run(user_prompt)
    return {"result": response}

4. Add the runner

if __name__ == "__main__":
    app.run()

Update your requirements.txt:

mcp
bedrock-agentcore

---

Step 4: Deploy to AgentCore Runtime

Deployment uses the AgentCore CLI from the starter toolkit. Two commands are all you need.

Configure the deployment

agentcore configure -e my_mcp_server.py --protocol MCP

The CLI walks you through a guided prompt:

• Execution role — Provide an IAM role ARN with AgentCore Runtime permissions
• ECR repository — Press Enter to auto-create one
• Dependency file — Auto-detected from the current directory
• OAuth — Type yes if you want authentication, then provide your Cognito discovery URL and client ID

Launch

agentcore launch

Behind the scenes, this command:

1. Builds an ARM64 Docker container with your server code and dependencies
2. Pushes the container image to Amazon ECR
3. Creates an AgentCore Runtime resource
4. Deploys your MCP server into an isolated microVM environment

On success, you receive an Agent Runtime ARN:

arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my_mcp_server-abc123

Save this ARN — you need it to invoke your server.

---

Step 5: Invoke and Test Your Deployed MCP Server

Your MCP server is now running on AWS. You can invoke it from any MCP client or from a Python script.

Remote invocation via Python

export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my_mcp_server-abc123"
export BEARER_TOKEN="your-oauth-bearer-token"

# my_mcp_client_remote.py

import asyncio
import os
import sys

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main():
    agent_arn = os.getenv("AGENT_ARN")
    bearer_token = os.getenv("BEARER_TOKEN")

    if not agent_arn or not bearer_token:
        print("Error: AGENT_ARN or BEARER_TOKEN not set")
        sys.exit(1)

    encoded_arn = agent_arn.replace(":", "%3A").replace("/", "%2F")
    mcp_url = (
        f"https://bedrock-agentcore.us-west-2.amazonaws.com"
        f"/runtimes/{encoded_arn}/invocations?qualifier=DEFAULT"
    )
    headers = {
        "authorization": f"Bearer {bearer_token}",
        "Content-Type": "application/json",
    }

    async with streamablehttp_client(
        mcp_url, headers, timeout=120, terminate_on_close=False
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # Discover tools
            tools = await session.list_tools()
            print("Deployed tools:")
            for tool in tools.tools:
                print(f"  - {tool.name}: {tool.description}")

            # Call a tool on the deployed server
            result = await session.call_tool(
                "generate_iam_policy",
                {
                    "actions": ["s3:GetObject", "s3:PutObject"],
                    "resource_arn": "arn:aws:s3:::my-bucket/*",
                },
            )
            print(f"\nGenerated policy:\n{result.content[0].text}")


asyncio.run(main())

You should see the same three tools you defined locally, now served from AgentCore Runtime with full session isolation, authentication, and observability.

Testing with MCP Inspector

You can also use the MCP Inspector for interactive testing. Point it at your deployed server's invocation URL with the appropriate bearer token, and you get a visual interface to discover tools, invoke them, and inspect responses.

---

What's Next?

You now have a production MCP server running on AgentCore Runtime. Here are natural next steps:

• AgentCore Gateway — Connect your agent to external APIs and third-party tools through the managed gateway.
• AgentCore Memory — Add persistent conversation context so your agent remembers prior interactions across sessions.
• AgentCore Identity — Integrate with your corporate identity provider for end-user authentication.
• Agent-to-Agent (A2A) — Deploy additional agents and let them communicate using the A2A protocol.
• Observability — Enable built-in tracing to capture agent reasoning steps via CloudWatch Transaction Search.

---

References

1. Host agent or tools with Amazon Bedrock AgentCore Runtime
2. Deploy MCP servers in AgentCore Runtime
3. MCP protocol contract
4. Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant
5. Get started with AgentCore Runtime direct code deployment
6. AgentCore MCP Server Tutorial — GitHub
7. AWS Bedrock AgentCore MCP Server — Open Source MCP Servers
8. Build long-running MCP servers on Amazon Bedrock AgentCore — AWS Blog
9. Accelerate development with the Amazon Bedrock AgentCore MCP server — AWS Blog
10. MCP Specification: Transports
11. Amazon Bedrock AgentCore Python SDK — GitHub
12. Amazon Bedrock AgentCore Starter Toolkit — GitHub

---

By Tebogo Tseka — AWS Practice Manager & Solutions Architect at Big Beard Web Solutions