# AgentCore MCP Server

A basic MCP (Model Context Protocol) server for deployment to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html).

## 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix-a))

## 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:
   ```bash
   python mcp_server.py
   ```
4. The server runs at `http://localhost:8000/mcp`

### Test locally with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

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

## Deploy to AWS AgentCore

### 1. Scaffold the project

```bash
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

```bash
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

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

```python
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.

```markdown
## 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
```