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

> Learn to configure the AWS MCP Server for Claude Code, Codex, and Cursor using the Agent Toolkit. Enable AWS skills effortlessly with unified configuration and agent-specific manifests. No manual setup required.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-29

---

**The Agent Toolkit for AWS provides a unified MCP configuration in [`plugins/aws-core/.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`.

```json
{
  "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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugin.json) manifest that references the MCP configuration via the `mcpServers` field. For example, [`plugins/aws-core/.cursor-plugin/plugin.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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:

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

```

Claude Code automatically loads the bundled MCP configuration from the `aws-core` plugin; no manual [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) editing is required. The marketplace entry references the underlying configuration in the `aws-core` plugin's [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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:

```bash
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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugin.json) from [`plugins/aws-core/.cursor-plugin/plugin.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/.cursor-plugin/plugin.json) to your local workspace, which in turn references the canonical [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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):

```json
{
  "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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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.

```python

# 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.cursor-plugin/marketplace.json).
- **Kiro** and custom deployments require manual creation of an [`mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/mcp.json) file with the server definition.
- The [`tools/validate.py`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/mcp.json) or custom [`plugin.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugin.json) to point to your private server URL. The [`tools/validate.py`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.