AgentCore Server

A basic MCP (Model Context Protocol) server for deployment to Amazon Bedrock AgentCore Runtime.

Project Structure

.devcontainer/
├── devcontainer.json
└── Dockerfile
mcp_server.py
requirements.txt

Prerequisites

• VS Code with the Dev Containers extension
• Docker running locally
• AWS account with credentials configured
• A Cognito user pool for authentication (see setup guide)

Local Development

1. Open this folder in VS Code
2. When prompted, click "Reopen in Container" (or run Dev Containers: Reopen in Container from the command palette)
3. Start the MCP server:

   python mcp_server.py
   

4. The server runs at http://localhost:8000/mcp

Test locally with MCP Inspector

npx @modelcontextprotocol/inspector

Then connect to http://localhost:8000/mcp in the inspector UI.

Deploy to AWS AgentCore

1. Scaffold the project

agentcore create --protocol MCP

Follow the prompts. When asked, provide your Cognito discovery URL and client ID.

2. Copy your server code

Copy mcp_server.py into the generated project directory and ensure the entrypoint in agentcore/agentcore.json points to it.

3. Deploy

agentcore deploy

This packages your code, uploads to S3, and creates the AgentCore runtime. You'll receive an agent runtime ARN on success.

4. Invoke the deployed server

export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:ACCOUNT_ID:runtime/YOUR_RUNTIME"
export BEARER_TOKEN="your-cognito-access-token"

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

async def main():
    encoded_arn = AGENT_ARN.replace(':', '%3A').replace('/', '%2F')
    url = f"https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/{encoded_arn}/invocations?qualifier=DEFAULT"
    headers = {"authorization": f"Bearer {BEARER_TOKEN}"}

    async with streamablehttp_client(url, headers, timeout=120, terminate_on_close=False) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.list_tools())

asyncio.run(main())

---

Agent Instructions

Use the following when providing this project as context to an AI coding agent.

## AgentCore MCP Server - Agent Context

This project is an MCP server targeting Amazon Bedrock AgentCore Runtime.

### Key facts
- Base image: `public.ecr.aws/docker/library/python:3.14`
- Runtime: Python with `mcp` package (FastMCP)
- Server binds to `0.0.0.0:8000/mcp` (required by AgentCore)
- Transport: `streamable-http` with `stateless_http=True`
- Node.js 24 LTS and `@aws/agentcore` CLI are available in the container
- Deploy with: `agentcore create --protocol MCP` then `agentcore deploy`

### Adding tools
Add new tools by decorating functions with `@mcp.tool()` in `mcp_server.py`:

    @mcp.tool()
    def my_tool(param: str) -> str:
        """Description of what this tool does"""
        return result

### Deployment workflow
1. `agentcore create --protocol MCP` — scaffolds project config
2. Ensure `agentcore/agentcore.json` entrypoint points to `mcp_server.py`
3. `agentcore deploy` — builds, uploads, and deploys
4. Invoke via the AgentCore endpoint with a Bearer token from Cognito

### Constraints
- Server MUST listen on `0.0.0.0:8000` (AgentCore requirement)
- The `/mcp` path is the default and expected by the platform
- Use `stateless_http=True` unless multi-turn/elicitation is needed