MCP Server on AgentCore Runtime: Connect to Amazon Quick

Connect an AgentCore Runtime, hosted MCP server to Amazon Quick

Giving a foundation model standardized, authenticated access to authoritative data and tools measurably reduces hallucination risk. Results vary by model and integration, so validate with before/after benchmarks (for example: tool-call accuracy, prompt-level precision, or end-to-end task success rates) in your environment.

This guide walks through the steps to host a Model Context Protocol (MCP) server on Amazon Bedrock AgentCore Runtime, expose it through AgentCore Gateway, and register the Gateway as an MCP connector in Amazon Quick so chat agents and Flows can call your tools. You’ll get the minimal project layout, dependency list, corrected environment commands, a runnable server example, a Dockerfile, agentcore CLI commands, the key IAM and auth artifacts, a curl-based smoke test, and the operational questions to answer before production.

What you’ll get

  • Minimal Python MCP server using FastMCP (stateless HTTP sample).
  • requirements.txt exact lines and a short Dockerfile.
  • Correct virtual-env and container build/run commands.
  • AgentCore CLI commands to configure and launch the runtime.
  • AgentCore Gateway inbound/outbound auth templates and a minimal IAM policy snippet.
  • A simple curl test to validate tool discovery and invocation.

Why MCP matters for agentic AI

“Model Context Protocol (MCP) servers allow foundation models to access external data and tools, supporting standardized, secure access to files, databases, and APIs.”

MCP standardizes how models call external tools and fetch authoritative context. That makes tooling reusable across agents, reduces bespoke connector work, and enables stateful, multi-turn behavior when implemented correctly.

Prerequisites

  • An AWS account and permission to create IAM roles, policies, and AWS resources for AgentCore, Amazon Cognito, and Amazon CloudWatch.
  • Amazon Quick set up with an Author or higher subscription.
  • Amazon Bedrock with AgentCore access and Anthropic models enabled per your account settings.
  • Local environment: Python 3.10+, AWS credentials configured, AWS CLI, AgentCore SDK, MCP library, and a running Docker daemon.
  • Familiarity with the AWS CLI and Python.

Code, dependencies, and environment

Start with this minimal project layout as a base:

mcp_server_project/
├── mcp_server.py # Main MCP server code
├── requirements.txt # Dependencies
└── __init__.py # Python package marker

requirements.txt should contain these lines exactly:

mcp>=1.10.0
boto3
bedrock-agentcore
bedrock-agentcore-starter-toolkit>=0.1.21
strands-agents

Corrected virtual environment and install commands (replace python3 with your platform’s Python if needed):

python3 -m venv sample-venv # Create virtual environment
source sample-venv/bin/activate # Activate virtual environment
pip install -r requirements.txt # Install the dependencies

Minimal FastMCP server (key lines). This sample runs the MCP endpoint at /mcp on port 8000 by binding to 0.0.0.0. AgentCore Runtime expects the MCP path to be reachable at /mcp; host and port are runtime/container configuration choices:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(host=”0.0.0.0″, stateless_http=True)

@mcp.tool()
def getOrder() -> int:
“””Get an order”””
return 123

@mcp.tool()
def updateOrder(orderId: int) -> int:
“””Update existing order”””
return 456

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

Notes and cautions about those lines:

  • The sample uses stateless_http=True for compatibility with the AgentCore Runtime configuration shown in the walkthrough. Validate with your AgentCore runtime version because implementations and requirements can change. stateless_http disables server-side session persistence, so the runtime can manage sessions externally.
  • transport=”streamable-http” enables streaming tool responses. Use transport=”http” if you prefer non-streaming behavior.
  • The function returns (123, 456) are placeholders. Implement tools that return JSON-serializable objects or well-documented schemas suitable for your agents.

Dockerfile and container steps

A minimal Dockerfile to containerize the server:

FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8000
CMD [“python”, “mcp_server.py”]

Build and run locally to sanity-check the endpoint:

docker build -t simple_mcp_server:latest .
docker run –rm -p 8000:8000 simple_mcp_server:latest

Ensure the container exposes port 8000 and that the MCP path is reachable at /mcp from the runtime/Gateway network. If your runtime uses a private subnet, the Gateway needs VPC connectivity to reach the runtime endpoint.

Deploy to AgentCore Runtime

After building your container image, use the AgentCore CLI to configure and launch the runtime. At minimum the sample commands are:

agentcore configure –entrypoint mcp_server.py –name simple_mcp_server
agentcore launch

AgentCore deployments may also require registering the image or pushing it to a container registry accessible to AgentCore. Consult your AgentCore tooling and account setup for image hosting steps. The walkthrough’s CLI snippets assume your image is accessible to AgentCore.

AgentCore Gateway: inbound and outbound auth

The Gateway mediates traffic between Amazon Quick (user-facing) and the AgentCore Runtime (MCP server). Configure two authentication flows:

  • Inbound Auth (Amazon Quick → Gateway): example uses Amazon Cognito issuing JWTs (OIDC discovery).
  • Outbound Auth (Gateway → AgentCore Runtime / MCP): the example uses OAuth 2.0 via AgentCore Identity + Cognito. The walkthrough uses OAuth 2.0; confirm your AgentCore/Gateway version and platform policies as other variants or providers may be supported.

Useful URL templates (replace placeholders with your values):

Cognito discovery URL (used for both inbound and outbound):
https://cognito-idp.{REGION}.amazonaws.com/{gw_user_pool_id}/.well-known/openid-configuration

Token URL (note: remove the underscore from the Cognito user pool ID in the hostname when required):
https://{user_pool_id_without_underscore}.auth.{REGION}.amazoncognito.com/oauth2/token

Use the same pattern replacing token with authorize for the authorize URL.

AgentCore Gateway target (Gateway calls the AgentCore Runtime MCP endpoint; the runtime ARN in the template must be URL-encoded):
https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{encoded_agentcore_runtime_mcp_server_arn}/invocations?qualifier=DEFAULT

Suggested names from the example:

  • Sample IAM policy name: “MCPServerRuntimePermissions”
  • Suggested role name: agentcore-sample-mcpgateway-role
  • AgentCore Gateway example name: ac-gateway-mcp-server

Minimal IAM policy snippet

Use a least-privilege approach and replace placeholders with your region/account/runtime IDs. The example policy allows the Gateway to invoke the runtime and retrieve secrets:

{
“Version”: “2012-10-17”,
“Statement”: [
{
“Sid”: “MCPServerRuntimePermissions”,
“Effect”: “Allow”,
“Action”: [
“bedrock-agentcore:InvokeAgentRuntime”,
“bedrock-agentcore:InvokeRegistryMcp”,
“secretsmanager:GetSecretValue”
],
“Resource”: [
“arn:aws:bedrock-agentcore:::runtime/“,
“arn:aws:bedrock-agentcore:::runtime//runtime-endpoint/*”
]
}
]
}

Register the MCP integration in Amazon Quick

  1. Open Amazon Quick → Connectors → Create for your team.
  2. Select Model Context Protocol (MCP) as the connector type.
  3. Provide the AgentCore Gateway resource URL, Inbound Auth (Cognito discovery URL, client ID/secret), and Outbound OAuth 2.0 details (token/authorize URLs and client credentials configured via AgentCore Identity).
  4. Choose private VPC connectivity if your runtime is inside a private network so the gateway and runtime can communicate over the VPC.

Operational note: Amazon Quick initially shows only listTools while it synchronizes tools from the MCP server. Tools become visible when the Action state transitions to Available or Ready.

Smoke test with curl

Use the local container or a reachable runtime endpoint to verify tool discovery and invocation. Example (replace placeholders):

# List tools (replace host/port as appropriate)
curl -X POST “http://localhost:8000/mcp/listTools” -H “Content-Type: application/json” -H “Authorization: Bearer <YOUR_JWT_OR_ACCESS_TOKEN>” -d ‘{}’

# Invoke a tool (example invoking getOrder)
curl -X POST “http://localhost:8000/mcp/invoke” -H “Content-Type: application/json” -H “Authorization: Bearer <YOUR_JWT_OR_ACCESS_TOKEN>” -d ‘{“name”:”getOrder”, “arguments”:{}}’

In Amazon Quick, use the Test Action APIs UI to exercise the Action as Quick would. If the Gateway and Cognito flows are configured correctly, Quick will discover tools and allow Action testing from the console.

Cleanup (recommended order)

To avoid charges, remove resources in roughly reverse creation order:

  • Delete the Amazon Quick chat agent or Flow.
  • Delete the Amazon Quick Action/Connector.
  • Delete the AgentCore Gateway and the Gateway IAM role.
  • Delete AgentCore Identity resources and any OAuth clients.
  • Delete the inbound and outbound Amazon Cognito user pools.
  • Delete the AgentCore Runtime (and any container images in registries if desired).

Operational considerations before production

The walkthrough provides a working end-to-end path. Production readiness requires more platform, security, and observability work.

Platform and ops

  • Scaling and performance: Define concurrency limits, autoscaling policies, and latency SLAs for AgentCore Runtime and Gateway. Run load tests that include model inference (Bedrock) to measure real latencies and throughput.
  • Cost and pricing: Model inference (Anthropic or other Bedrock models), Gateway invocations, runtime execution time, and monitoring all incur cost. Budget and benchmark accordingly.
  • Observability: Ship structured logs (CloudWatch), metrics, and traces for the Quick → Gateway → Runtime → tool chain, and create alerts for failures, auth rejects, and high tail latency.
  • Error handling: Define retry semantics, idempotency requirements for tools, and how tool errors are surfaced to agents and users.
  • VPC / networking: If runtimes are private, ensure the Gateway has the correct VPC connectivity and that DNS and endpoint routing are resolvable from the Gateway.

Security and compliance

  • Auth lifecycles: Implement token caching, refresh flows, and rotation for OAuth client secrets. Confirm token lifetimes match your session models.
  • Least-privilege IAM: Narrow the sample policy to the minimum resources needed. Avoid wildcard resources in production.
  • Secrets management: Store secrets in Secrets Manager and grant read access narrowly to only the Gateway role.
  • Enterprise IdPs: If you use Okta, Azure AD, or another SSO, map OIDC discovery and OAuth flows to your IdP and test federation end-to-end.

Common pitfalls

  • Forgetting to expose /mcp in the container or misconfiguring port mappings so the Gateway cannot reach the endpoint.
  • Failing to URL-encode the runtime ARN when constructing the AgentCore Gateway target URL.
  • Using very short-lived tokens without implementing refresh logic in the Gateway, causing intermittent auth failures.

Key takeaways, questions you’ll ask

  • What does MCP actually give my agent?

    MCP provides a standardized interface so models can call external tools, files, and APIs securely, which reduces hallucination risk and enables stateful, multi-turn interactions when paired with session management.

  • What authentication is required?

    Inbound (user → Gateway) typically uses JWT/OIDC (the example uses Amazon Cognito). Outbound (Gateway → AgentCore Runtime / MCP) in the example uses OAuth 2.0 with AgentCore Identity + Cognito. Confirm your AgentCore/Gateway version and platform policies, other providers or configurations may be supported.

  • Where should my MCP server listen?

    Expose an HTTP listener that binds to 0.0.0.0 and mounts the MCP endpoint at /mcp (the sample uses port 8000). AgentCore Runtime expects the MCP path to be reachable at /mcp; ensure your container maps EXPOSE 8000 and the runtime/Gateway network can reach it.

  • How do I connect Amazon Quick to the runtime?

    Configure an AgentCore Gateway with inbound/outbound auth, register it in Amazon Quick (Connectors → Create → Model Context Protocol), and provide the Gateway URL plus Cognito/OAuth artifacts. If your runtime is private, enable VPC connectivity so the Gateway can reach it.

  • How do I test the integration?

    Use the local container or a reachable runtime and curl to call /mcp/listTools and /mcp/invoke (send a valid Authorization token). Then use Amazon Quick’s Test Action APIs and attach the Action to a chat agent or Flow to run multi-turn tests.

Next steps

  • Clone and run the referenced notebooks to see a runnable example:
    https://github.com/awslabs/agentcore-samples/blob/main/06-workshops/01-AgentCore-runtime/02-hosting-MCP-server/hosting_mcp_server.ipynb
  • Build the Docker image, run it locally, and exercise the curl tests above.
  • Register the Gateway in Amazon Quick, use Test Action APIs, then attach the Action to a chat agent or Flow for end-to-end verification.

Authors to search for deeper dives and related guidance: Vivek Ghatala, Vishnu Elangovan, Sreeja Das, and Lucien LaScala. For the code samples, see the AgentCore samples repository: https://github.com/awslabs/agentcore-samples

Addressing the operational checklist, scaling, observability, error handling, and security hardening, turns a working demo into a reliable, auditable production capability for your agents.

1