# How to Configure AWS MCP Server with Claude Code, Codex, or Cursor

> Learn to configure AWS MCP Server with Claude Code, Codex, or Cursor. Install the aws-core plugin, define your MCP server, and verify connectivity for seamless integration.

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

---

**To configure the AWS MCP Server with Claude Code, Codex, or Cursor, install the `aws-core` plugin for your specific agent, add an MCP server definition JSON file pointing to the AWS MCP endpoint, and verify connectivity using your agent's MCP list command.**

The **AWS MCP (Model Context Protocol) Server** provides a unified, sandboxed way for AI-coding agents to call AWS services, run scripts, and search documentation. According to the `aws/agent-toolkit-for-aws` repository, this server integrates with Claude Code, Codex, and Cursor through a plugin-based architecture that falls back to standard AWS CLI commands if the server becomes unavailable.

## Prerequisites

Before configuring the AWS MCP Server, ensure you have:

- **AWS credentials** configured in your environment (the server authenticates using your local AWS profile)
- **Node.js or uvx** installed to run the MCP proxy (the examples below use `uvx`)
- Access to the `aws/agent-toolkit-for-aws` repository to install the `aws-core` plugin

## Configure AWS MCP Server with Claude Code

Claude Code supports MCP servers through three scopes: **local** (`~/.claude.json`), **project** ([`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json)), and **user** (global settings).

### Install the aws-core Plugin

Install the plugin using Claude Code's built-in command:

```bash
/plugin install aws-core@claude-plugins-official
/reload-plugins

```

According to the [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md) in the repository root, this command bundles the MCP Server configuration and a curated set of skills.

### Add the MCP Server Definition

Create your MCP configuration file based on your preferred scope. For local scope, create `~/.claude.json`:

```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"
      ]
    }
  }
}

```

As documented in [`skills/specialized-skills/database-skills/aurora-dsql/references/platforms/claude-code.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/aurora-dsql/references/platforms/claude-code.md), this JSON defines how Claude Code connects to the AWS MCP endpoint.

### Verify Connectivity

Run the verification command to confirm the server is reachable:

```bash
claude mcp list

```

You should see `aws` listed with a **Connected** status. This confirms that the server can authenticate with your AWS credentials and that the sandbox is ready.

## Configure AWS MCP Server with Codex

Codex follows a similar pattern but uses its own marketplace and configuration paths.

### Add the Repository to Codex

First, add the AWS toolkit to Codex's marketplace:

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

```

Then install the `aws-core` plugin inside Codex by navigating to `/plugins` and selecting *aws-core*.

### Configure the MCP Definition

Codex uses the same JSON structure as Claude Code. Create the configuration at `~/.codex/mcp.json` (or [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) for project scope):

```json
{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@1.6.3",
        "https://aws-mcp.us-east-1.api.aws/mcp"
      ]
    }
  }
}

```

The file [`skills/specialized-skills/database-skills/aurora-dsql/references/platforms/codex.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/aurora-dsql/references/platforms/codex.md) documents this structure specifically for Codex users.

### Verify the Connection

In Codex's terminal, run:

```bash
codex mcp list

```

Confirm that the AWS MCP Server appears with a connected status before proceeding.

## Configure AWS MCP Server with Cursor

Cursor integrates the AWS MCP Server through its Team Marketplace feature.

### Import the Repository

Navigate to *Settings → Plugins → Team Marketplaces → Add Marketplace → Import from Repo* and enter:

```

aws/agent-toolkit-for-aws

```

As noted in the repository's [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md) (lines 67-71), this imports the toolkit into your Cursor environment.

### Install the Plugin

Open the **Plugins panel** and install **aws-core**. Cursor reads the same JSON files located under `skills/.../platforms/`, specifically referencing [`skills/specialized-skills/database-skills/aurora-dsql/references/platforms/cursor.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/aurora-dsql/references/platforms/cursor.md) (or reusing the generic Codex definition if the Cursor-specific file is not present).

### Add MCP Configuration

Paste the following JSON into Cursor's *MCP Settings* dialog (accessible from the *Plugins* pane):

```json
{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@1.6.3",
        "https://aws-mcp.us-east-1.api.aws/mcp"
      ]
    }
  }
}

```

### Verify Installation

Use the built-in terminal in Cursor to verify:

```bash
cursor mcp list

```

The AWS MCP Server should appear as **Connected**.

## Using MCP Tools in Your Skills

Once configured, agents invoke AWS services through the MCP Server using standardized tool calls. The server handles authentication, sandboxing, and CloudTrail logging.

### Example Tool Call

From within a skill or direct prompt, invoke AWS operations like this:

```json
{
  "tool": "aws___call_aws",
  "args": {
    "service": "s3",
    "operation": "list_buckets",
    "parameters": {}
  }
}

```

### Available Tools

The `aws-core` plugin provides three primary MCP tools:

- **`aws___call_aws`** – Invoke any AWS API operation (e.g., `s3:ListBuckets`, `ec2:DescribeInstances`)
- **`aws___run_script`** – Execute sandboxed scripts with AWS credentials
- **`aws___search_documentation`** – Query AWS documentation indexes

If the MCP Server is unreachable, agents automatically fall back to plain AWS CLI commands, ensuring your skills remain functional regardless of server status.

## Key Configuration Files

The following source files in the `aws/agent-toolkit-for-aws` repository contain the authoritative configuration specifications:

- **[`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md)** – Overall quick-start and installation instructions for all three agents
- **[`plugins/aws-core/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/README.md)** – Detailed plugin installation commands and MCP proxy options
- **[`skills/specialized-skills/database-skills/aurora-dsql/references/platforms/claude-code.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/aurora-dsql/references/platforms/claude-code.md)** – Claude Code-specific MCP scopes and JSON schema
- **[`skills/specialized-skills/database-skills/aurora-dsql/references/platforms/codex.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/aurora-dsql/references/platforms/codex.md)** – Codex-specific platform definitions
- **[`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md)** – Recommended rule set that forces agents to prefer the MCP Server when available

## Summary

- **Install the `aws-core` plugin** for your specific agent (Claude Code, Codex, or Cursor) to bundle MCP Server capabilities
- **Create an MCP server definition** JSON file specifying the `uvx` command with `mcp-proxy-for-aws` and the AWS endpoint URL
- **Choose your scope** carefully: local (`~/.claude.json` or `~/.codex/mcp.json`), project ([`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json)), or user/global settings
- **Verify connectivity** using your agent's `mcp list` command before invoking AWS tools
- **Leverage automatic fallback** to AWS CLI if the MCP Server becomes unavailable, ensuring continuous operation

## Frequently Asked Questions

### What is the AWS MCP Server and why do I need it?

The AWS MCP Server is a Model Context Protocol implementation that provides a sandboxed, audited gateway for AI agents to access AWS services. According to the `aws/agent-toolkit-for-aws` source code, it forwards requests to AWS, logs them in CloudTrail, and returns results to the agent. While optional—agents can fall back to AWS CLI—it provides better security, logging, and consistency across Claude Code, Codex, and Cursor.

### Can I use the same MCP configuration JSON for all three agents?

Yes, the core JSON structure remains identical across Claude Code, Codex, and Cursor. All three agents accept the same `mcpServers` object with `command` and `args` arrays. However, the **file location** differs: Claude Code uses `~/.claude.json`, Codex uses `~/.codex/mcp.json`, and Cursor uses its internal MCP Settings dialog. Refer to the platform-specific files in `skills/specialized-skills/database-skills/aurora-dsql/references/platforms/` for exact placement.

### What happens if the MCP Server is offline or unreachable?

The skills in the `aws-core` plugin contain fallback logic that automatically switches to standard AWS CLI commands if the MCP Server cannot be reached. As implemented in the repository, this makes the configuration safe and backward-compatible—your agent will continue to function using local AWS credentials and CLI commands rather than failing.

### Do I need to configure AWS credentials separately for the MCP Server?

No, the MCP Server uses your existing AWS credentials from your environment. When you run `claude mcp list` or the equivalent verification command, the server attempts to authenticate using your default AWS credential chain (environment variables, `~/.aws/credentials`, or IAM roles). Ensure your credentials are valid and have the necessary permissions before verifying the MCP connection.