ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect an MCP Server to Amazon Bedrock

Connect an MCP server to Amazon Bedrock with AgentCore Gateway, version-aware requests, authentication, tool discovery, troubleshooting, and working examples.

By the ScreenshotNeo team1 October 20267 min read

Use Amazon Bedrock AgentCore Gateway as the MCP entry point. Create a gateway, configure inbound authorization, add your MCP server as a target, synchronize its advertised capabilities, then have your client call tools/list and tools/call through the gateway. Bedrock Converse remains a separate model-inference API; it does not register MCP servers or provide the MCP tool transport.

This guide covers the managed gateway architecture, direct protocol requests, protocol-version differences, authentication boundaries, AgentCore Runtime requirements, failure diagnosis, and a ScreenshotNeo option for agents that need website screenshots.

1. Choose the connection architecture

“Connect an MCP server to Bedrock” can describe two separate operations:

Need Use
Expose one or more MCP servers through an AWS-managed endpoint AgentCore Gateway with MCP server targets
Send a prompt and conversation history to a foundation model Amazon Bedrock Runtime Converse
Let an agent discover and invoke tools An MCP client calling the gateway’s tools/list and tools/call methods

AgentCore Gateway can aggregate MCP targets behind one MCP endpoint. Configure the gateway and targets before connecting your application or agent. See AWS’s gateway concepts and gateway creation procedure.

2. Prerequisites and deployment checklist

  1. An AWS account and a Region where the required AgentCore and Bedrock services are available.
  2. An MCP server reachable by the gateway, with its endpoint, advertised tools, and authentication method documented.
  3. A gateway configuration with an inbound authorization mechanism for your application or agent.
  4. Outbound credentials that let the gateway authenticate to the MCP target.
  5. The gateway’s configured supportedVersions value. Do not assume the protocol version from an old sample.

Keep these identities separate. Inbound authorization controls who may call the gateway. Outbound authorization controls how the gateway calls your MCP target. The endpoint and target configuration determine which credential provider is valid.

3. Create the gateway and add the MCP target

  1. Create an AgentCore Gateway and record its MCP endpoint.
  2. Configure inbound authorization for your application, service, or agent.
  3. Add the external MCP server as an MCP target, including its endpoint and outbound authentication.
  4. Confirm the target advertises tool capability. Prompts and resources are optional and are synchronized when advertised.
  5. Synchronize the target when the selected configuration requires it. AWS describes synchronization as the step that performs protocol handshakes and indexes capabilities.

Follow the AWS MCP server target guide for target-specific fields and synchronization behavior.

4. Discover tools through the gateway

After authorization succeeds, call tools/list against the gateway MCP endpoint. Inspect every returned tool’s name, description, and JSON input schema before allowing a model to select it.

export GATEWAY_MCP_URL='https://YOUR-GATEWAY-MCP-ENDPOINT'
export AUTH_TOKEN='YOUR_INBOUND_TOKEN'

curl -sS -X POST "$GATEWAY_MCP_URL" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: YOUR_SUPPORTED_VERSION' \
  -H 'Mcp-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The exact headers and body metadata depend on the gateway’s supported protocol revision. AWS’s list-tools example shows the request shape for the configured service version.

5. Call a tool

Use the tool name and arguments from the discovered schema. Validate arguments in your client before sending them; a model-generated object should never bypass schema validation.

curl -sS -X POST "$GATEWAY_MCP_URL" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: YOUR_SUPPORTED_VERSION' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: YOUR_TOOL_NAME' \
  --data '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"YOUR_TOOL_NAME",
      "arguments":{}
    }
  }'

Replace the tool name and argument object with values returned by tools/list. AWS documents the gateway call flow in Call a tool in an AgentCore gateway.

6. Handle MCP protocol versions correctly

Protocol version mismatches are a common cause of confusing 4xx responses. AWS documents revisions including 2026-07-28. That revision uses request metadata headers and corresponding body metadata and does not use the older initialize handshake. Earlier supported revisions use initialization before discovery and calls.

Version-aware procedure

  1. Read the gateway’s supportedVersions configuration.
  2. Select one version and use its exact header names, metadata fields, and request sequence.
  3. For an older initialize-based revision, send initialize, process the response, then send the required initialized notification before tools/list.
  4. For 2026-07-28, send the method and protocol metadata required by AWS for each request; do not add an obsolete initialize exchange.

Use the AWS Use an AgentCore gateway reference as the authority when service support changes.

7. Python client example

import os
import requests

url = os.environ["GATEWAY_MCP_URL"]
token = os.environ["AUTH_TOKEN"]
version = os.environ["MCP_PROTOCOL_VERSION"]

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "MCP-Protocol-Version": version,
    "Mcp-Method": "tools/list",
}

response = requests.post(
    url,
    headers=headers,
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
    timeout=60,
)
response.raise_for_status()
print(response.json())

For a call, change Mcp-Method to tools/call, add Mcp-Name, and send params: {"name": "...", "arguments": {...}}. Adjust the body metadata to match the selected AWS protocol revision.

8. Node.js client example

const gatewayUrl = process.env.GATEWAY_MCP_URL;
const token = process.env.AUTH_TOKEN;
const version = process.env.MCP_PROTOCOL_VERSION;

const res = await fetch(gatewayUrl, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
    Accept: 'application/json, text/event-stream',
    'MCP-Protocol-Version': version,
    'Mcp-Method': 'tools/list'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
    params: {}
  })
});

if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log(await res.json());

Use the same version-specific changes described above for tools/call.

9. Put Bedrock Converse beside MCP, not inside it

An MCP client can provide discovered tool definitions to an agent loop. The loop decides whether to call a tool, sends the call to the gateway, and then gives the result back to the model. If you use Bedrock Converse, that API handles the model message exchange; it does not replace the MCP transport.

aws bedrock-runtime converse \
  --model-id YOUR_MODEL_ID \
  --messages '[{"role":"user","content":[{"text":"Summarize the latest tool result."}]}]'

Model IDs, Regions, request features, and SDK versions vary. Verify availability for your deployment in the Converse API reference.

10. AgentCore Runtime-specific requirements

If the MCP server runs on AgentCore Runtime, follow its separate protocol contract: Streamable HTTP is required, and stateless mode is the default recommendation for compatibility with session handling and load balancing. Do not apply this Runtime deployment requirement to every MCP server host.

Read the AgentCore Runtime MCP protocol contract before selecting session behavior.

11. Authentication and network design

  • Protect the gateway endpoint with its configured inbound authorization.
  • Store tokens and target credentials in a secrets manager or runtime secret store, never in source code.
  • Configure outbound credentials for the target independently from client credentials.
  • Restrict the gateway’s network path to the target endpoint and required AWS services.
  • Log request IDs, method names, status codes, and latency while redacting arguments that contain secrets or personal data.

12. Troubleshooting

Symptom Likely cause Fix
401 or 403 from the gateway Inbound token is missing, expired, or intended for the target Use the gateway’s inbound authorization and verify audience, scope, and expiry.
Gateway reaches no target Outbound credentials or endpoint are wrong Test the target independently and correct the target authentication configuration.
Unsupported protocol version Client headers/body do not match supportedVersions Read the configured version and copy its AWS request format exactly.
tools/list returns no expected tool Target was not synchronized or does not advertise tool capability Synchronize the target and inspect its advertised capabilities.
Tool call validation error Arguments do not match the returned input schema Validate required fields, types, enums, and nested objects before calling.
Timeouts or intermittent failures Target latency, cold start, network path, or overloaded service Set bounded client timeouts, retry only idempotent operations, and record gateway and target latency separately.
Runtime session failures Stateful assumptions conflict with load balancing Use Streamable HTTP and stateless mode where the Runtime contract recommends it.

13. Performance, reliability, and cost considerations

  • Discover tools once per process or deployment and cache the schema until the target configuration changes.
  • Keep tool descriptions and schemas precise so the model receives less context.
  • Use request deadlines shorter than your overall agent deadline; reserve time for retries and model responses.
  • Retry network failures with exponential backoff only when repeating the operation is safe. Use idempotency keys where the target supports them.
  • Measure gateway time, target time, model time, and serialization time separately.
  • Expect costs from the AWS services you enable, including gateway, Runtime, model inference, networking, logging, and any target service. Check current AWS pricing for your Region and traffic pattern.

14. Or skip the browser setup

If one of your MCP tools needs website screenshots, ScreenshotNeo provides an HTTP screenshot API and an MCP server. A single request returns PNG, JPEG, WebP, or PDF output.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests; r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90); open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Start with 1,000 free screenshots per month.

15. FAQ

Does Bedrock Converse connect to an MCP server directly?

No. Converse handles model inference. An MCP client or AgentCore Gateway handles tool discovery and invocation.

Must every MCP server use AgentCore Gateway?

No. Gateway is the managed aggregation and authorization route described here. A direct client-to-server arrangement is another architecture.

What should I do when an AWS example uses initialize?

Check the gateway’s supported protocol version. Older revisions use initialization; the documented 2026-07-28 revision uses request metadata instead.

Are prompts and resources guaranteed to appear?

No. AWS describes them as optional capabilities that synchronize when the target advertises them.

Can an API Gateway endpoint be used as a target?

AWS documents API Gateway REST API targets with constraints, including public REST API support and credential-provider limits. Treat that as a separate target type and verify its current requirements.

Keep reading