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

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:

/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, the JSON structure defines the server command and arguments:

{
  "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:

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:

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 (project scope). The configuration structure mirrors Claude Code's format, as detailed in skills/specialized-skills/database-skills/aurora-dsql/references/platforms/codex.md:

{
  "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:

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 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:

{
  "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:

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:

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

Run Scripts

Execute scripts in the sandboxed environment using aws___run_script:

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

Search Documentation

Query AWS documentation using aws___search_documentation:

{
  "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 in your project root for project scope. According to 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 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.

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