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

> Configure AWS MCP Server using aws-core plugin and JSON definition pointing to your AWS Model Context Protocol endpoint. Verify connectivity with your agent's list command.

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

---

**Configure the AWS MCP Server by installing the `aws-core` plugin and adding an MCP server definition JSON that points to the AWS Model Context Protocol endpoint, then verify connectivity using your agent's list command.**

The **AWS MCP (Model Context Protocol) Server** in the `aws/agent-toolkit-for-aws` repository provides a secure, sandboxed gateway for AI coding agents to invoke AWS services, run scripts, and query documentation. This unified interface supports Claude Code, Codex, and Cursor through a standardized configuration that handles authentication, logging to CloudTrail, and safe execution of AWS API calls.

## What is the AWS MCP Server?

The **AWS MCP Server** acts as a bridge between AI agents and AWS services. When configured, agents route requests through `aws___call_aws`, `aws___run_script`, or `aws___search_documentation` tools instead of executing raw AWS CLI commands. The server validates credentials, executes calls in a sandboxed environment, and returns results to the agent. If the server becomes unreachable, agents automatically fall back to standard AWS CLI commands, ensuring your skills remain functional without code changes.

## Prerequisites

Before configuring the MCP server, ensure you have:

- **AWS credentials** configured locally (via `~/.aws/credentials` or environment variables)
- **Node.js and uvx** installed to run the MCP proxy
- Access to the `aws/agent-toolkit-for-aws` repository or marketplace

## Configuration Steps for Claude Code

Claude Code requires the `aws-core` plugin and an MCP definition file placed in one of three scopes: local (user-level), project-level, or system-wide.

### Step 1: Install the Plugin

Install the official `aws-core` plugin using Claude Code's plugin command:

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

```

### Step 2: Add the MCP Server Definition

Create the MCP configuration file at the appropriate scope. For local scope (user-wide), place it in `~/.claude.json`. According to the setup documentation 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), the JSON structure defines the server command and arguments:

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

```

### Step 3: Verify Connectivity

Run the Claude Code MCP list command to confirm the server is connected:

```bash
claude mcp list

```

You should see `aws` listed with a **Connected** status, indicating the server can authenticate with your AWS credentials.

## Configuration Steps for Codex

Codex follows a similar pattern but uses different installation paths and marketplace commands.

### Step 1: Add to Marketplace

Add the repository to Codex's marketplace using the CLI, as documented in the main [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md):

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

```

### Step 2: Install the Plugin

Navigate to the Plugins panel in Codex and install the `aws-core` plugin bundle.

### Step 3: Configure MCP Server

Codex reads MCP definitions from `~/.codex/mcp.json` (local scope) or [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) (project scope). The configuration structure mirrors Claude Code's format, as detailed in [`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):

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

```

### Step 4: Verify Installation

Check the server status using:

```bash
codex mcp list

```

## Configuration Steps for Cursor

Cursor integrates the AWS MCP Server through its Team Marketplace and plugin settings.

### Step 1: Import the Repository

Import the toolkit as a Team Marketplace in Cursor:
- Navigate to **Settings → Plugins → Team Marketplaces → Add Marketplace**
- Select **Import from Repo** and enter `aws/agent-toolkit-for-aws`

### Step 2: Install aws-core

Open the Plugins panel and install the **aws-core** bundle. If available, reference [`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) for Cursor-specific configuration; otherwise, reuse the Codex configuration format.

### Step 3: Configure via MCP Settings

Paste the MCP server JSON into the **MCP Settings** dialog accessible from the Plugins pane, or create a local configuration file:

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

```

### Step 4: Verify Connection

In Cursor's built-in terminal, run:

```bash
cursor mcp list

```

Confirm the AWS MCP Server appears as **Connected**.

## Verifying the MCP Server Connection

Regardless of which agent you use, verification follows a consistent pattern. The `aws-core` plugin adds curated skills that automatically detect the MCP server. When you run your agent's list command (`claude mcp list`, `codex mcp list`, or `cursor mcp list`), look for:

- **Server Name**: `aws`
- **Status**: Connected
- **Capability**: `call_aws`, `run_script`, `search_documentation`

A successful verification proves that the server can authenticate with your AWS credentials and that the sandbox environment is ready for execution.

## Using AWS MCP Tools

Once configured, invoke AWS services through the MCP server using the following tool signatures. The server forwards these requests to AWS, logs them in CloudTrail, and returns the results.

### Call AWS Services

Use `aws___call_aws` to invoke any AWS API:

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

```

### Run Scripts

Execute scripts in the sandboxed environment using `aws___run_script`:

```json
{
  "tool": "aws___run_script",
  "args": {
    "script": "#!/bin/bash\naws s3 ls"
  }
}

```

### Search Documentation

Query AWS documentation using `aws___search_documentation`:

```json
{
  "tool": "aws___search_documentation",
  "args": {
    "query": "EC2 instance types"
  }
}

```

## Summary

- **Install the `aws-core` plugin** from the `aws/agent-toolkit-for-aws` repository using your agent's specific marketplace or plugin command.
- **Add the MCP server definition** JSON to the appropriate scope file (`~/.claude.json`, `~/.codex/mcp.json`, or Cursor's MCP Settings).
- **Verify connectivity** using `claude mcp list`, `codex mcp list`, or `cursor mcp list` to ensure the server shows as Connected.
- **Use MCP tools** (`aws___call_aws`, `aws___run_script`, `aws___search_documentation`) for secure, logged AWS operations with automatic fallback to AWS CLI if the server is unavailable.

## Frequently Asked Questions

### What file path should I use for the Claude Code MCP configuration?

For Claude Code, place the MCP server definition in `~/.claude.json` for local (user) scope, or [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) in your project root for project scope. According to [`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), these scopes determine whether the configuration applies globally or only to specific directories.

### Does the AWS MCP Server work offline?

No, the AWS MCP Server requires an internet connection to reach `https://aws-mcp.us-east-1.api.aws/mcp`. However, the `aws-core` plugin includes fallback logic that executes AWS CLI commands directly when the MCP server is unreachable, ensuring your skills continue to function without modification.

### Which agents support the `aws-core` plugin?

The `aws-core` plugin supports **Claude Code**, **Codex**, and **Cursor**. Each agent loads the plugin through its respective marketplace system, but the underlying MCP server configuration and tool signatures remain consistent across all three platforms.

### Where can I find the recommended rules for forcing MCP usage?

The recommended agent rules are located in [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) within the repository. This file contains rule sets that instruct agents to prefer the MCP Server when available, ensuring consistent authentication and logging behavior across all AWS interactions.