Configuring the AWS MCP Server for Claude Code, Codex, and Cursor: A Complete Guide

The Agent Toolkit for AWS provides a unified MCP configuration in plugins/aws-core/.mcp.json that plugs into Claude Code, Codex, and Cursor through agent-specific manifests, enabling AWS skills via the aws-mcp server without manual server setup.

The Agent Toolkit for AWS (aws/agent-toolkit-for-aws) exposes AWS services to AI coding agents through the Model Context Protocol (MCP). This guide explains how the toolkit's plugin-centric architecture routes the same MCP server configuration to Claude Code, Codex, and Cursor, each consuming the canonical definition found in plugins/aws-core/.mcp.json.

Understanding the MCP Server Architecture

Centralized Configuration

All agents ultimately reference the same MCP server definition located at plugins/aws-core/.mcp.json. This file defines the aws-mcp server entry that points to the AWS-hosted proxy at https://aws-mcp.us-east-1.api.aws/mcp and pins the proxy version to mcp-proxy-for-aws@1.6.3.

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@1.6.3",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

Plugin Manifest Indirection

Each plugin contains a plugin.json manifest that references the MCP configuration via the mcpServers field. For example, plugins/aws-core/.cursor-plugin/plugin.json contains {"mcpServers": "./.mcp.json"}, allowing Cursor to resolve the configuration relative to the plugin directory. This indirection enables the same JSON to be reused across all supported agents.

Configuring Claude Code

Claude Code discovers the MCP configuration automatically through the Anthropic marketplace.

Marketplace Installation

Install the aws-core plugin from the official Claude marketplace:

/plugin install aws-core@claude-plugins-official

Claude Code automatically loads the bundled MCP configuration from the aws-core plugin; no manual .mcp.json editing is required. The marketplace entry references the underlying configuration in the aws-core plugin's .mcp.json file.

Configuring Codex

Codex consumes the toolkit through its own marketplace system.

Adding the Toolkit to Codex

First, register the repository in the Codex marketplace:

codex plugin marketplace add aws/agent-toolkit-for-aws

Then, inside the Codex interface, execute /plugins and install the aws-core plugin. Codex reads the MCP configuration from plugins/aws-core/.mcp.json, exposing AWS tools such as aws___call_aws and aws___search_documentation to the agent.

Configuring Cursor

Cursor uses a team marketplace import workflow to discover plugins.

Team Marketplace Import

Cursor reads the monolithic marketplace definition in .cursor-plugin/marketplace.json, which enumerates available plugins including aws-core and aws-agents. To configure:

1. Open Cursor Settings → Plugins → Team Marketplaces
2. Select "Add Marketplace" → "Import from Repo"
3. Provide the URL https://github.com/aws/agent-toolkit-for-aws
4. Install the desired plugin (e.g., aws-core) from the Plugins panel

When installed, Cursor copies the plugin.json from plugins/aws-core/.cursor-plugin/plugin.json to your local workspace, which in turn references the canonical .mcp.json configuration.

Manual Configuration for Kiro and Custom Setups

For agents like Kiro that lack automatic marketplace integration, or for custom on-premises deployments, manual configuration is required.

Local MCP.json Setup

Create a local MCP configuration file at ~/.kiro/settings/mcp.json (or the equivalent path for your agent):

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@1.6.3",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

This manual approach is also useful for adding private MCP servers. The toolkit's validation script at tools/validate.py ensures that any custom configuration includes the required command or url fields, maintaining a consistent contract across agents.

Runtime Tool Execution

Once configured, the toolkit's skill loader inspects the plugin manifest, resolves the relative path to .mcp.json, and creates an MCPClient object using the specified command and arguments.

MCP Tool Fallback Behavior

Skills invoke MCP tools directly (e.g., call_aws s3 ls), but remain compatible with plain AWS CLI if the MCP server is unavailable. When the aws-mcp server is reachable, requests route through the AWS-hosted proxy; otherwise, the skill falls back to executing aws s3 list-buckets locally.

# Inside a skill script

result = await tools.call_aws("s3", "list-buckets", {})
print(result["Buckets"])

Summary

• The canonical MCP configuration lives in plugins/aws-core/.mcp.json and defines the aws-mcp server using uvx and the AWS-hosted proxy.
• Claude Code installs automatically from the marketplace with no manual configuration.
• Codex requires adding the repository to the marketplace via codex plugin marketplace add before installing the plugin.
• Cursor imports plugins through Team Marketplaces using .cursor-plugin/marketplace.json.
• Kiro and custom deployments require manual creation of an mcp.json file with the server definition.
• The tools/validate.py script validates MCP configurations during CI to ensure required fields are present.

Frequently Asked Questions

How do I pin a specific MCP proxy version?

The proxy version is pinned in plugins/aws-core/.mcp.json within the args array (e.g., mcp-proxy-for-aws@1.6.3). When manually configuring agents, specify this exact version string to ensure compatibility with the toolkit's expected protocol.

Can I use a private MCP server instead of the AWS-hosted proxy?

Yes. Edit your local mcp.json or custom plugin.json to point to your private server URL. The tools/validate.py script will verify that your configuration includes the required command or url fields, ensuring the agent can establish the MCP connection.

Why does Cursor require a different installation method than Claude Code?

Cursor uses a team-based marketplace import system that reads .cursor-plugin/marketplace.json to enumerate plugins, whereas Claude Code pulls directly from the Anthropic marketplace. Cursor requires the additional step of importing the repository URL before plugins appear in the UI, though both ultimately consume the same plugins/aws-core/.mcp.json configuration.

What happens if the MCP server is unavailable?

The toolkit implements a fallback mechanism. Skills first attempt to use the MCP tool (e.g., aws___call_aws); if the server is unreachable, they automatically fall back to executing the equivalent AWS CLI command locally, ensuring workflows remain functional even during connectivity issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}