mirror of
https://github.com/awslabs/amazon-bedrock-agentcore-samples.git
synced 2025-09-08 20:50:46 +00:00
109 lines
3.1 KiB
Markdown
109 lines
3.1 KiB
Markdown
|
# TypeScript MCP Server on Amazon Bedrock AgentCore
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This tutorial demonstrates how to host a TypeScript-based MCP (Model Context Protocol) server using the Amazon Bedrock AgentCore runtime environment.
|
||
|
|
|
||
|
|
|
||
|
|
### Tutorial Details
|
||
|
|
|
||
|
|
| Information | Details |
|
||
|
|
|:--------------------|:----------------------------------------------------------|
|
||
|
|
| Tutorial type | Hosting typescript MCP server |
|
||
|
|
| Tool type | MCP server |
|
||
|
|
| Tutorial components | Hosting typescript MCP server on AgentCore Runtime |
|
||
|
|
| Tutorial vertical | Cross-vertical |
|
||
|
|
| Example complexity | Easy |
|
||
|
|
| SDK used | Anthropic's typescript SDK for MCP |
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- Node.js v22 or later
|
||
|
|
- Docker (for containerization)
|
||
|
|
- Amazon ECR (Elastic Container Registry) for storing Docker images
|
||
|
|
- AWS account with access to Bedrock AgentCore
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## AgentCore Runtime Service Contract
|
||
|
|
|
||
|
|
Refer to the [official service contract documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html).
|
||
|
|
|
||
|
|
**Runtime configuration:**
|
||
|
|
- **Host:** `0.0.0.0`
|
||
|
|
- **Port:** `8000`
|
||
|
|
- **Transport:** Stateless `streamable-http`
|
||
|
|
- **Endpoint Path:** `POST /mcp`
|
||
|
|
|
||
|
|
## Local Development
|
||
|
|
|
||
|
|
1. Install dependencies
|
||
|
|
|
||
|
|
```
|
||
|
|
npm install
|
||
|
|
```
|
||
|
|
|
||
|
|
2. Set up AWS credentials
|
||
|
|
```
|
||
|
|
aws configure
|
||
|
|
export AWS_ACCESS_KEY_ID=your_access_key
|
||
|
|
export AWS_SECRET_ACCESS_KEY=your_secret_key
|
||
|
|
export AWS_REGION=us-east-1
|
||
|
|
```
|
||
|
|
|
||
|
|
3. Start server
|
||
|
|
```
|
||
|
|
npm run start
|
||
|
|
```
|
||
|
|
|
||
|
|
4. Test locally using [MCP inspector](https://github.com/modelcontextprotocol/inspector)
|
||
|
|
|
||
|
|
```
|
||
|
|
npx @modelcontextprotocol/inspector
|
||
|
|
```
|
||
|
|
|
||
|
|
## Docker Deployment
|
||
|
|
|
||
|
|
1. Create ECR Repository
|
||
|
|
```
|
||
|
|
aws ecr create-repository --repository-name mcp-server --region us-east-1
|
||
|
|
```
|
||
|
|
2. Build and Push Image to ECR
|
||
|
|
```
|
||
|
|
# Get login token
|
||
|
|
aws ecr get-login-password --region us-east-1 | \
|
||
|
|
docker login --username AWS --password-stdin [account-id].dkr.ecr.us-east-1.amazonaws.com
|
||
|
|
|
||
|
|
docker buildx --platform linux/arm64 \
|
||
|
|
-t [account-id].dkr.ecr.us-east-1.amazonaws.com/mcp-server:latest --push .
|
||
|
|
```
|
||
|
|
|
||
|
|
3. Deploy to Bedrock AgentCore
|
||
|
|
|
||
|
|
- Go to AWS Console → Bedrock → AgentCore → Create Agent
|
||
|
|
- Choose MCP as the protocol
|
||
|
|
- Configure Agent Runtime:
|
||
|
|
- Image URI: [account-id].dkr.ecr.us-east-1.amazonaws.com/mcp-server:latest
|
||
|
|
- Set IAM Permissions for Bedrock model access
|
||
|
|
- Deploy and test in the Agent Sandbox
|
||
|
|
|
||
|
|
|
||
|
|
4. Construct the Encoded ARN MCP URL
|
||
|
|
|
||
|
|
```
|
||
|
|
echo "agent_arn" | sed 's/:/%3A/g; s/\//%2F/g'
|
||
|
|
```
|
||
|
|
|
||
|
|
```
|
||
|
|
https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{encoded_arn}/invocations?qualifier=DEFAULT
|
||
|
|
```
|
||
|
|
|
||
|
|
5. Use the MCP url with [MCP inspector](https://github.com/modelcontextprotocol/inspector).
|
||
|
|
|
||
|
|
## References
|
||
|
|
- https://aws.amazon.com/bedrock/agentcore/
|
||
|
|
- https://github.com/modelcontextprotocol/typescript-sdk
|
||
|
|
- https://github.com/modelcontextprotocol/inspector
|
||
|
|
|
||
|
|
|