Skip to main content
The AWS MCP Server gives an AI agent access to most of the 15,000+ AWS API operations, plus current AWS documentation, through a small set of tools. Connect it through MCP Manager and the gateway logs, inspects, and governs every one of those calls. You do not connect it by pasting its URL. The AWS MCP Server authenticates with AWS IAM SigV4, not OAuth and not a static token. Instead you run AWS’s proxy, mcp-proxy-for-aws, on your own machine and add it as a Workstation server. This guide shows you how.
Why you cannot paste the URL. SigV4 signs each request with credentials that expire. A fixed header value cannot do this, so the signing must happen on your machine. When you submit a URL, MCP Manager’s authentication detection looks for OAuth, pre-registered OAuth, a token in custom headers, or an open server. The AWS MCP Server is none of these.If you already added the URL as a Remote server and got an invalid_redirect_uri error, see the first entry under Gotchas.
This guide reflects AWS’s setup at the time of writing. AWS’s AWS MCP Server User Guide is authoritative and may be newer. The credentials flow, the endpoints, the proxy version, and all IAM behavior come from AWS. If a problem is specific to how AWS authenticates, ask AWS.
This flow needs the Deploy new workstation instances and Create and configure managed and workstation servers capabilities. If you do not see the Workstation option, ask a workspace administrator. See the capabilities reference.

​
How the connection works

Three pieces run on your machine:

​
Where your AWS credentials live

The AWS proxy runs as an ordinary process in your terminal, not in a sandbox. It reads your local credentials directly: your aws login session, the files under ~/.aws, and the AWS_PROFILE set in that shell. Only the tunnel runs in a container, and it never touches your credentials. It forwards MCP traffic to the local port and nothing else. So:
  • Run aws login and the Start your MCP server command on the same machine, in a shell that can see those credentials.
  • If you use a named profile, set AWS_PROFILE in that shell. Set the operating region with the proxy’s --metadata AWS_REGION=… argument.
Your credentials never leave your workstation. The signing and the call to AWS both happen there. MCP Manager governs and logs the tool calls that pass through the gateway, but never handles your AWS keys.

​
Before you start

  • An AWS account and an IAM identity (user or role). The proxy acts with exactly this identity’s permissions, so keep them least-privilege.
  • The AWS CLI, version 2.32.0 or later, installed. Use aws login: it rotates credentials every 15 minutes and keeps the session valid for up to 12 hours.
  • uv installed. It provides the uvx runner that starts the AWS proxy.
  • Docker running, for the tunnel — the same requirement as any workstation server.
  • A decision on region and access. Which AWS Region operations run in, and whether this identity should be read-only.

​
Connect the server

1

Authenticate the AWS CLI

Sign in, then confirm the credentials work:
terminal
get-caller-identity prints the account and identity you expect.AWS also supports SSO, IAM access keys, and cross-account roles — see Sign in with the AWS CLI. Use aws login if you can. It renews credentials for you, which prevents the most common failure: an expired session token mid-task.
2

Install uv

The AWS proxy runs through uvx, which ships with uv. If you do not have it:
Make sure uvx is on the PATH of the shell that will run the proxy. A later spawn uvx ENOENT error means it is not.
3

Scope the agent's AWS access (recommended)

The AWS MCP Server has no IAM permissions of its own. Your existing IAM permissions authorize every call, so the identity from Step 1 is the real boundary.To make an agent read-only, do not rely on a client-side flag. Enforce it with an IAM policy or Service Control Policy that uses AWS’s condition keys, aws:ViaAWSMCPService and aws:CalledViaAWSMCP. These let the same identity keep full access for a human while acting read-only through the MCP server. See Understanding IAM for managed AWS MCP servers.
These condition keys apply only to calls made through the MCP server. If your AI client also has a shell or AWS CLI tool, the agent can run aws … directly. That call goes straight to AWS under your credentials and bypasses the condition keys. The identity’s own permissions are the durable control.
4

Create a Workstation server

Go to MCP Servers and click Add. Choose Workstation (“The MCP servers run on personal computers”). Enter a Server Name such as AWS, then click Save MCP server.MCP Manager opens the server’s Server instances tab.
5

Add the AWS proxy as a STDIO instance

Click Add server instance. Name the instance (for example AWS MCP) and choose Launch new (STDIO), the path for a server that starts from a command. Then fill in:Click Next. Two details matter:
  • Pin the version. A pin such as ==1.6.4 prevents a breaking change from arriving on a later start, and it avoids a PyPI check on every launch. Check the releases for the current version.
  • The endpoint Region and the operating Region are different. The URL decides which AWS MCP Server you talk to. --metadata AWS_REGION=… decides where your operations run. Without it, every operation runs in us-east-1, even from the Frankfurt endpoint.
6

Run the first command: start the AWS proxy

The Deploy workstation proxy screen shows two commands, each with a Copy command button. Run both, in two terminals, and leave both running. Nothing connects until both are up. This is where this setup most often stalls.Copy the first command, Start your MCP server, and run it in a terminal that can see your credentials from Step 1. MCP Manager builds it from what you entered:
Terminal 1: AWS proxy
Leave it running. The first start is slow, because uvx downloads the AWS proxy. Your server is then published at http://localhost:8000/mcp.
The command names two different proxies. mcp-proxy, before the --, is the wrapper MCP Manager generates. mcp-proxy-for-aws, after the --, is AWS’s proxy, the one that signs each request. Everything after the -- is what you entered in the previous step.
Check this half before you continue. In a third terminal, run curl -i http://localhost:8000/mcp. Any answer means the proxy is up. connection refused means it is not, and no tunnel debugging will help. To go further and list the tools, point an MCP inspector at the same URL.
7

Run the second command: start the tunnel

Copy the second command, Start MCPM’s workstation proxy, and run it in a second terminal. This command connects your machine to MCP Manager. Without it, the gateway cannot reach the proxy you just started. It carries a registration token unique to your instance:
Terminal 2: MCP Manager tunnel
A dashboard opens and shows each step as the tunnel comes up. Wait for the steps to finish, and leave this terminal running.
If the dashboard stops at “Tailscale daemon started”, a corporate proxy or secure web gateway (Zscaler, Netskope, and similar) is probably blocking outbound access to headscale.mcpmanager.ai on TCP 443. See When a network proxy blocks the connection.
8

Test the connection

With both terminals running, return to the browser and click Test connection. MCP Manager reaches the proxy through the tunnel, discovers the AWS tools, and opens the instance’s Features page.If you see “Connection failed. Make sure the workstation proxy is running and try again,” check that both commands are still running. A closed terminal — or a command that was never run — is the usual cause. Then click Test connection again.
The Features page lists the AWS tools. You can now assign this server to a gateway like any other.
Both terminals must keep running. This is not one-time setup. Terminal 1 signs your requests; terminal 2 carries the traffic. Close either one and the server goes offline until you start it again. Start both again after a reboot, or after your aws login session expires.

​
What your agent gets

The AWS MCP Server provides a small set of tools in two groups:
  • Knowledge tools fetch current AWS documentation and best-practice “skills” at query time, so the agent is not limited to what its training data knew.
  • API tools run AWS operations with your IAM credentials, including a sandboxed Python runner for multi-step work.
To see exactly what this server provides, open the instance’s Features page. It lists every tool, with the description each one gives your agent. AWS changes this set from time to time; Understanding the MCP Server tools is AWS’s reference for it.

​
Per-developer or centralized access

AWS credentials must live wherever the proxy runs. That shapes how you roll this out:
  • Per-developer (recommended). Each developer runs the proxy with their own IAM identity, as above. Every call is attributable to that person, and their credentials stay on their machine. This also fits short-lived aws login sessions well.
  • Centralized. To put one shared AWS identity behind a team gateway, run the proxy as a Managed server on infrastructure you provide. Give that host an IAM role rather than long-lived access keys, and scope it tightly. A shared credential has a much larger blast radius than a per-developer session, and you cannot centralize the connection without centralizing a credential.
Working across several AWS accounts? Configure multiple CLI profiles and pass them to the proxy with --profile or the AWS_MCP_PROXY_PROFILES environment variable. The proxy then adds an optional aws_profile parameter to its tools, so the agent can route a call to a specific account. See Multi-profile support.

​
Gotchas & things to keep in mind

  • You added the URL as a Remote server and were never sent to AWS to sign in. If you pasted https://aws-mcp.us-east-1.api.aws/mcp (with or without ?oauth=initialize) as a Remote server, it fails while MCP Manager registers itself with AWS — before any browser redirect. The error reads:
    This is expected. You cannot fix it in MCP Manager or in your AWS account: AWS Sign-in accepts OAuth registrations only from http://localhost and http://127.0.0.1 addresses, and from a short list of hosted client domains that AWS maintains. Delete the remote server and follow Connect the server instead.
  • ExpiredTokenException is the most common error. Session tokens are short-lived, often one hour. Refresh your credentials — aws login does this automatically — then click Test connection again, or restart the proxy.
  • A -32602 Invalid request parameters error usually means expired credentials. Some clients report the proxy’s LoginRefreshRequired as a generic JSON-RPC -32602, which sends you looking for a malformed request instead of an auth problem (proxy issue #304). If a working connection starts failing this way, run aws login first.
  • Set --metadata AWS_REGION=… deliberately. Without it, operations run in us-east-1 whichever endpoint you use. This is the most common region surprise.
  • Run the proxy where your credentials are. The Start your MCP server command runs the proxy in that terminal. If the shell cannot see your aws login session or AWS_PROFILE, signing fails. See Where your AWS credentials live.
  • Remove older AWS MCP servers from your AI client. If you used aws-api-mcp-server or aws-knowledge-mcp-server, AWS recommends removing them so overlapping tools do not confuse the agent.
  • Auditing lives in two places, with one naming quirk. AWS publishes metrics to the CloudWatch AWS-MCP namespace and records calls in CloudTrail — but CloudTrail logs tool names without the aws___ prefix (for example retrieve_skill). Write your queries accordingly. MCP Manager’s Logs capture the same calls as they pass through the gateway, tied to the person who made them.

​
Further reading

Workstation MCP Servers

How the tunnel, the local router, and the governance model work.

Connect a workstation MCP server

The hands-on walkthrough of the workstation flow, with both generated commands.

Find & Connect MCP Servers

How MCP Manager detects a server’s authentication type, and how to find other servers.

Authentication & Identity

How MCP Manager authenticates to servers, and how identities are stored and shared.

​
External sources

AWS MCP Server User Guide

AWS’s authoritative setup guide — credentials, endpoints, client configuration, and troubleshooting.

MCP Proxy for AWS

The open-source SigV4 proxy you run locally, with its current version and options.

Understanding the MCP Server tools

The full reference for the knowledge and API tools the server provides.

Understanding IAM for managed AWS MCP servers

How IAM authorizes the server, and how to restrict agent actions with condition keys.

Multi-profile support

Configure multiple AWS accounts and route calls with the aws_profile parameter.

The AWS MCP Server is now generally available

AWS’s GA announcement — the design, the tools, and the IAM/SigV4 model.