AWS Builder Center

Builder Center

Convert Public APIs to MCP Tools with API Gateway + AgentCore Gateway

Convert Public APIs to MCP Tools with API Gateway + AgentCore Gateway

Turn your existing API Gateway REST APIs into MCP-compatible tools that AI agents (eg. Claude Desktop) can discover and invoke.

Lester

AI agents need tools to interact with the real world, and the Model Context Protocol (MCP)  has become the standard for connecting agents to those tools.
If you already have REST APIs in Amazon API Gateway, you can expose them as MCP-compatible tools through Amazon Bedrock AgentCore Gateway - no custom wrapper code required. This is especially relevant for SaaS companies looking to make their existing APIs accessible to customers' AI agents.
This post walks you through setting up this integration by adding an API Gateway stage directly as a target.
AgentCore Gateway also supports using an OpenAPI specification file to define your API target - that approach will be covered in a future tutorial. To keep things focused, this guide covers public APIs that don't require authentication and uses no-auth on the AgentCore Gateway itself - ideal for development, testing, or public-facing tools. A follow-up guide will cover securing the gateway and connecting to APIs that require IAM, API key, or OAuth-based authorization.
Important: A gateway with no inbound authorization is accessible to anyone with the endpoint URL. Do not use this configuration for production workloads or APIs that return sensitive data.

Architecture Overview

The diagram above shows the full request flow from an MCP client to your backend, including where inbound and outbound authorization checkpoints sit. In this guide, both are set to "No Auth."
Request flow:
  1. The MCP client (Claude Desktop, Claude Code, or Kiro) sends tools/list or tools/call requests over Streamable HTTP to the AgentCore Gateway endpoint
  2. Inbound Auth (None) — the gateway accepts the request without verifying any credentials. In production, this checkpoint would validate a JWT token or IAM credentials.
  3. AgentCore Gateway translates the MCP request into a standard HTTP request matching the API Gateway resource and method
  4. Outbound Auth (None) — the gateway forwards the HTTP request to API Gateway without attaching any authorization headers. In production, this would sign the request with SigV4 or attach an API key.
  5. API Gateway routes the request to the backend integration (Lambda, DynamoDB, etc.) and returns the response
  6. AgentCore Gateway formats the response as an MCP result and returns it to the client
Sample DynamoDB Database Schema

Prerequisites

  • An AWS account
  • An existing public REST API deployed to a stage in Amazon API Gateway — no authorization configured on the methods
  • An IAM role or user with permissions to create and manage AgentCore Gateway resources (the BedrockAgentCoreFullAccess managed policy works for getting started)
  • Familiarity with API Gateway concepts (stages, resources, methods)

Step 1: Check Your API Gateway Configuration

Before creating the gateway, verify your REST API meets these requirements:
  1. Only public REST APIs are supported for the API Gateway target type. The default endpoint of your API cannot be disabled.
  2. Every method you want to expose must either have an operation name defined in API Gateway, or you'll need to create a name override when adding the target. This name is used as the MCP tool name that agents use to interact with your method.
  3. Your API methods must define a Method Response (e.g., application/json in the response body). AgentCore Gateway uses this to correctly translate responses back to the MCP client.
  4. Your API must be in the same account and Region as your AgentCore Gateway.
  5. If you don't have an existing API Gateway to test this deployment, you can download the sample code for deploying an API Gateway here and deploy it via terraform for testing: Link 

Step 2: Create the AgentCore Gateway and Add Your API as a Target

  1. Open the AgentCore console 
  2. In the left navigation pane, select Gateways
  3. Choose Create gateway
  1. In the Gateway details section: Enter a Gateway name (e.g., ecommerce-transactions-mcp)
  2. In the Inbound Auth configurations section, select No Authorization. This makes the gateway accessible without authentication — suitable for dev/testing or public tools.
  1. In the Permissions section: Choose Create and use a new service role to let the console create a role with the necessary permissions
  2. In the Target section, choose API Gateway as the target type and configure:
    • Target name — enter a descriptive name (e.g., ecommerce-mcp-v1)
    • Target description — briefly describe what this target exposes
    • REST API — select the REST API you want to expose
    • Stage — select the deployed stage
  3. Under Select API resources, choose the specific resources and methods to expose as MCP tools. If you don't select a resource, agents cannot view its documentation or invoke the endpoint
  4. For any method that doesn't already have an operation name defined, create a name override. This name becomes the MCP tool name that agents use
Note: Every method you expose must have either an operation name defined in API Gateway or a name override. Without a name, the tool won't be usable by agents.
  1. Under Outbound Auth configuration, select No authorization. This works for public APIs that don't require authentication. A follow-up tutorial will cover configuring outbound authorization for APIs that require IAM, API key, or OAuth-based authentication.
  2. Choose Create gateway
Note the Gateway ID and Gateway URL from the gateway details page. You'll need both in the following steps.

Step 3: Verify the Target

To confirm the target was created:
  1. In the API Gateway console, select AgentCore targets in the main navigation pane. This view shows all AgentCore Gateways that have access to your APIs.

Test with Claude/Kiro

AgentCore Gateway exposes a Streamable HTTP MCP endpoint. Since we configured the gateway with no inbound authorization, you can connect directly without any tokens or credentials. You can use Claude Desktop, Claude Code, or Kiro as your MCP client.

Option 1: Claude Desktop

Claude Desktop connects to remote MCP servers through the Connectors UI. To add your AgentCore Gateway:
  1. Open Claude Desktop
  2. Go to Customize > Add Custom Connector
  3. Add a new connector with your gateway's MCP endpoint URL
Note: Remote MCP connections from Claude Desktop are brokered server-side through Anthropic's cloud infrastructure. Claude Desktop will not connect to remote servers that are configured directly via claude_desktop_config.json.

Option 2: Claude Code

Claude Code supports remote MCP servers natively over Streamable HTTP. Add your AgentCore Gateway:
1
claude mcp add --transport http agentcore-gateway <YOUR_GATEWAY_URL>
Verify the server is connected:
1
claude mcp list
Or within a Claude Code session, run /mcp to check server status and see the available tools.
You can also add it via a .mcp.json file at your project root for team sharing:
1
2
3
4
5
6
7
8
{
"mcpServers": {
"agentcore-gateway": {
"type": "http",
"url": "<YOUR_GATEWAY_URL>"
}
}
}

Option 3: Kiro

Add the AgentCore Gateway as a remote MCP server in Kiro's configuration. Open the workspace MCP config at .kiro/settings/mcp.json (or the user-level config at ~/.kiro/settings/mcp.json for cross-project access):
1
2
3
4
5
6
7
8
9
{
"mcpServers": {
"agentcore-gateway": {
"url": "<YOUR_GATEWAY_URL>",
"disabled": false,
"autoApprove": []
}
}
}
Save the file and the server connects automatically. Open the Kiro panel to confirm the MCP server status and view the discovered tools.

Verify the Integration

Once connected through any of the options above, start by confirming the tools are available:
1
2
3
4
5
6
7
You: What tools do you have access to?

Claude: I have access to the following tools:
1. ecommerce-mcp-v1___getTransaction — Returns a transaction by its ID
2. ecommerce-mcp-v1___getTotalTransactions — Returns the total number of transactions
3. ecommerce-mcp-v1___createTransaction — Creates a new transaction
4. x_amz_bedrock_agentcore_search — Search for tools by query
Then try each API with a natural language prompt:
Get total transactions
1
2
3
4
You: How many transactions are in the system?

Claude: [Calling tool: ecommerce-mcp-v1___getTotalTransactions]
There are currently 3 transactions in the system.
Create a new transaction
1
2
3
4
5
6
7
8
9
10
You: Create a new transaction for a Mechanical Keyboard for $129.99, status completed.

Claude: [Calling tool: ecommerce-mcp-v1___createTransaction]
Transaction created successfully:
- Transaction ID: TXN-A3F7B
- Item: Mechanical Keyboard
- Amount: $129.99
- Currency: USD
- Status: completed
- Date: 2026-04-04
Get a transaction by ID
1
2
3
4
5
6
7
8
9
You: Look up transaction TXN-00020

Claude: [Calling tool: ecommerce-mcp-v1___getTransaction]
Here are the details for transaction TXN-A3F7B:
- Item: Curved Gaming Monitor 32-inch
- Amount: $799.99
- Currency: USD
- Status: completed
- Date: 2026-03-30

Adding New APIs and Updating MCP Tools

As your API evolves, you'll add new resources and methods to API Gateway. Here's how to make those changes visible as MCP tools in AgentCore Gateway.

Updating the Target

When you add new resources or methods to your REST API in API Gateway:
  1. Deploy the changes to your API Gateway stage as usual
  2. Open the API Gateway console  and select your REST API
  3. In the main navigation pane, choose MCP targets
  4. Select the target linked to your AgentCore Gateway
  5. Choose Edit
  6. Under Select API resources, select the new resources and methods you want to expose
  7. Choose Save
The target updates immediately. AgentCore Gateway picks up the new tool definitions without requiring a gateway restart or redeployment.

Refreshing the MCP Client

After updating the target in AgentCore Gateway, your MCP client needs to pick up the new tools:
  • Claude Desktop — Disconnect and reconnect the connector to re-fetch the updated tool list
  • Claude Code — run /mcp to check the server status, then start a new session. Claude Code fetches the tool list at session start, so new tools appear in the next conversation.
  • Kiro — reconnect the MCP server from the Kiro panel (click the refresh icon next to the server), or reload the window. Kiro re-fetches the tool list on reconnect.
Tip: Use the tools/list MCP method to verify the updated tool set. If you enabled semantic search on your gateway, the x_amz_bedrock_agentcore_search tool also indexes the new tools automatically.

Removing Tools

To stop exposing a specific API method as an MCP tool, edit the target in the API Gateway console and deselect the resources or methods you want to remove. Reconnect your MCP client after making changes to refresh the tool list.

Clean Up

To avoid ongoing charges, delete the resources you created:
  1. Open the AgentCore console 
  2. Navigate to your gateway
  3. In the Targets tab, select the target and choose Delete
  4. After deleting all targets, select the gateway and choose Delete
  5. If you created a service role specifically for this walkthrough, delete it in the IAM console 

Enable Observability

AgentCore Gateway integrates with Amazon CloudWatch Logs, AWS CloudTrail, and AWS X-Ray. Enable application logs on your gateway to see detailed invocation traces including tool calls, request parameters, and responses.
Key metrics available in CloudWatch:
  • Invocation metrics — Invocations, ConcurrentExecutions, Sessions
  • Performance metrics — Latency, Duration, TargetExecutionTime
  • Error metrics — Throttles, SystemErrors, UserErrors
  • Usage metrics — TargetType, IngressAuthType, EgressAuthType

References

# amazon-bedrock-agentcore# claude# mcp# mcp-integration# api-gateway
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article