> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect AWS
> Connect the AWS MCP Server to MCP Manager. Because it authenticates with AWS IAM SigV4 rather than OAuth or a token header, you run AWS's mcp-proxy-for-aws proxy locally and add it as a Workstation server — so every call to AWS's 15,000+ APIs is signed with your own IAM credentials on your machine and governed by the gateway.
The [AWS MCP Server](https://aws.amazon.com/blogs/aws/the-aws-mcp-server-is-now-generally-available/) gives an AI agent authenticated access across AWS — most of the 15,000+ AWS API operations, plus always-current AWS documentation — through a small, fixed set of tools. Connecting it through MCP Manager means every one of those calls is logged, inspected, and governed by the gateway, instead of an agent talking to your AWS account unattended.
It connects differently from most servers in this section. The AWS MCP Server authenticates with **AWS IAM SigV4**, not OAuth and not a static token, so you don't paste its URL into MCP Manager. Instead you run AWS's open-source proxy, [`mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws), on your own machine, and add it to MCP Manager as a **[Workstation server](/mcp-gateway-concepts/mcp-servers/workstation)**. This guide walks that path end to end.
**Why this isn't a paste-a-URL connection.** When you submit a URL, MCP Manager's [authentication
detection](/mcp-server-guides/overview#how-mcp-manager-detects-the-authentication-type) resolves to OAuth, pre-registered OAuth, a token in custom
headers, or an open server. The AWS MCP Server uses **none** of these. AWS states it plainly: the server "uses AWS Identity and Access Management
(IAM) and IAM SigV4 authentication." Remote MCP authorization is built on OAuth 2.1, so AWS's managed endpoint can't be reached with a static token
header — you connect to it "through a proxy" that "bridges the world of IAM authentication to OAuth." SigV4 signs **each request** over its payload
and a timestamp using credentials that expire, so a one-time header value can't satisfy it — which is why the signing has to happen locally in the
proxy, and why the AWS MCP Server is connected as a local/stdio Workstation server rather than a remote URL.
This guide reflects AWS's setup at the time of writing. **AWS's own [AWS MCP Server User
Guide](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) is authoritative** and may be more current.
The credentials flow, the regional endpoints, the proxy version, and all IAM behavior come from AWS, not from MCP Manager. If a step here has
drifted or a problem is specific to how AWS authenticates, AWS's documentation and support are the fastest path to an answer.
Connecting a workstation server is gated by the **Deploy new workstation instances** and **Create and configure managed and workstation servers**
capabilities. If you don't see the **Workstation** option when you add a server, your role doesn't have the relevant capability or the feature isn't
enabled for your workspace — ask a workspace administrator. See the [capabilities reference](/deployment/rbac-and-roles/capabilities).
## How the connection works
You run the AWS proxy on your machine; MCP Manager reaches it through an encrypted tunnel and governs every call. Concretely, [`supergateway`](https://github.com/supercorp-ai/supergateway) launches `mcp-proxy-for-aws` and republishes it as a local HTTP endpoint, a small tunnel-agent container carries the MCP traffic to the MCP Manager gateway over a [WireGuard](https://www.wireguard.com/) tunnel, and the proxy signs each AWS API request with SigV4 — using your local AWS credentials — and sends it on to AWS.
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Lato, sans-serif','lineColor':'#6a6b76','primaryColor':'#e0e2e8','primaryTextColor':'#12141d','primaryBorderColor':'#6a6b76','edgeLabelBackground':'#ffffff','textColor':'#12141d'}}}%%
flowchart LR
Client["🤖
AI app or agent"] --> GW["🛡️
MCP Manager gateway
logs · inspects · governs"]
GW -->|"WireGuard tunnel"| Agent
subgraph WS["Your workstation — credentials never leave"]
direction LR
Agent["Tunnel agent
(container, host network)"] --> SG["supergateway
STDIO → HTTP on :8000"]
SG --> Proxy["mcp-proxy-for-aws
signs each request"]
Creds[("🔐
Local AWS credentials
aws login · ~/.aws")] -.->|read on each request| Proxy
end
Proxy -->|"SigV4-signed HTTPS"| AWS["🔌
AWS MCP Server
aws-mcp.us-east-1.api.aws"]
AWS --> Svc["🔌
AWS services
15,000+ APIs"]
classDef gateway fill:#0086ff,color:#ffffff,stroke:#062b4c,stroke-width:2px;
classDef client fill:#80cbc4,color:#062b4c,stroke:#00796b,stroke-width:1.5px;
classDef datastore fill:#062b4c,color:#ffffff,stroke:#0086ff,stroke-width:1.5px;
classDef external fill:#e0e2e8,color:#2c2c37,stroke:#9ca1ab,stroke-width:1px,stroke-dasharray:4 3;
class GW gateway;
class Client client;
class Creds datastore;
class AWS,Svc external;
style WS fill:transparent,stroke:#9ca1ab,stroke-dasharray:4 3,color:#6a6b76;
```
### Where your AWS credentials live
**The proxy runs on your machine as an ordinary process — not inside a sandboxed container that's walled off from your credentials.** `supergateway` launches `mcp-proxy-for-aws` in the same terminal where you run it, so the proxy reads your local AWS credentials directly: your [`aws login`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) session, the files under `~/.aws`, and the `AWS_PROFILE` and region from that shell.
The **tunnel-agent container is the only containerized piece**, and it never touches your AWS credentials. It runs with host networking and only forwards MCP traffic to the local HTTP port the proxy listens on. So the practical rule is:
* Run `aws login` **and** the generated *Start your MCP server* command on the **same machine, in a shell that can see those credentials**.
* If you authenticate with a named profile, set `AWS_PROFILE` in that shell (and set the operating region with the proxy's `--metadata AWS_REGION=…` argument).
Your AWS credentials never leave your workstation — the SigV4 signing and the outbound call to AWS both happen there. MCP Manager governs and logs the MCP tool calls flowing through the gateway, but the gateway never handles your AWS keys.
## Before you start
Bring the following before you open MCP Manager:
* [ ] **An AWS account and an IAM identity** (user or role) with permissions for what you want the agent to do. Follow least privilege — the proxy acts with exactly the permissions this identity has.
* [ ] **The AWS CLI, version `2.32.0` or later**, [installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and authenticated. `aws login` is the simplest method: it automatically rotates your credentials every 15 minutes and keeps the session valid for up to 12 hours.
* [ ] **[`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed** on the workstation — it provides the `uvx` runner the proxy is launched with.
* [ ] **Docker running**, for the workstation tunnel agent (the same prerequisite as any [workstation server](/tutorials/connect-a-workstation-server)).
* [ ] **A decision on region and access posture** — which AWS Region operations should run in, and whether this identity should be read-only.
This is a fiddly first connection. If it doesn't come up, validate the proxy in isolation with an [open MCP
inspector](/advanced/validate-mcp-servers) — point it at the local proxy endpoint and list its tools — to confirm the AWS side works before you
start debugging the workstation tunnel.
## Connect the server
Sign in so the proxy has credentials to sign with, then confirm they work:
```bash terminal theme={null}
aws login
aws sts get-caller-identity
```
`get-caller-identity` should print the account and identity you expect. AWS supports other credential methods (SSO, IAM access keys, cross-account roles) — see [Sign in with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) — but `aws login` is recommended because it renews credentials for you, which avoids the most common failure (an expired session token mid-task).
The proxy runs through `uvx`, which ships with `uv`. If it isn't installed:
```bash macOS / Linux theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell Windows theme={null}
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Make sure `uvx` ends up on your `PATH` in the shell that will run the proxy — a "`spawn uvx ENOENT`" error later means it isn't found.
The AWS MCP Server defines **no IAM permission of its own** — your existing per-service IAM permissions are what authorize every call, so the identity you signed in with in Step 1 is the real boundary. Keep it tight.
For a read-only agent, don't rely on a client-side flag; enforce it with an IAM policy or Service Control Policy keyed on AWS's MCP condition keys, `aws:ViaAWSMCPService` and `aws:CalledViaAWSMCP`. These let you allow a human to perform mutating actions while the **same** identity, when acting through the MCP server, is restricted to read-only. See [Understanding IAM for managed AWS MCP servers](https://aws.amazon.com/blogs/security/understanding-iam-for-managed-aws-mcp-servers/).
The condition keys apply only to calls made **through** the MCP server. If your AI client also has a shell or AWS CLI tool, an agent can run `aws …` directly — that request goes straight to AWS under your credentials and **bypasses** the MCP condition keys entirely. The underlying identity's own least-privilege permissions are the durable control.
On the [MCP Servers](https://app.mcpmanager.ai/settings/servers) page, click **Add**. In the **Add an MCP server** dialog, choose **Workstation**
("The MCP servers run on personal computers"). In **Server Name**, enter something like `AWS`, then click **Save MCP server**. MCP Manager takes you
to the server's **Server instances** tab.
On the **Server instances** tab, click **Add server instance**. In the **Connect a workstation MCP server** dialog, give the instance a name (for example `AWS MCP`) and choose **Launch new (STDIO)** — the path for a server that starts from a command. Then fill in:
| Field | Value |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Command** | `uvx mcp-proxy-for-aws==1.6.1` |
| **Command arguments** | `https://aws-mcp.us-east-1.api.aws/mcp`, then `--metadata`, then `AWS_REGION=us-east-1` (add each as a separate argument) |
| **Port** | `8000` |
Click **Next**. Two details matter here:
* **Pin the proxy version.** AWS recommends pinning (for example `==1.6.1`) so a client launch can't pull in a breaking change; an unpinned `@latest` also re-checks PyPI on every start, slowing connection. Check the [releases](https://github.com/aws/mcp-proxy-for-aws) for the current version — AWS's own examples currently pin `1.6.0`.
* **The endpoint Region and the operating Region are different things.** The endpoint in the URL decides which AWS MCP Server you talk to; `--metadata AWS_REGION=…` decides where your AWS operations actually run. Without the metadata, **every operation defaults to `us-east-1`** even if you connected to the Frankfurt endpoint.
| Endpoint Region | MCP endpoint URL |
| ----------------------------------- | ------------------------------------------ |
| US East (N. Virginia) — `us-east-1` | `https://aws-mcp.us-east-1.api.aws/mcp` |
| Europe (Frankfurt) — `eu-central-1` | `https://aws-mcp.eu-central-1.api.aws/mcp` |
MCP Manager now shows two commands to run on your machine, each with a **Copy command** button. Run the first — **Start your MCP server** — in a terminal **where your AWS credentials from Step 1 are available**, because that terminal is where the proxy actually runs and reads them. Built from what you entered, it looks like this:
```bash terminal theme={null}
npx -y supergateway --stdio "uvx mcp-proxy-for-aws==1.6.1 https://aws-mcp.us-east-1.api.aws/mcp --metadata AWS_REGION=us-east-1" --port 8000 --outputTransport streamableHttp --stateful
```
Run the second command — the **workstation proxy** (`docker run …`, with a registration token the wizard fills in) — in another terminal to bring up the encrypted tunnel. The full mechanics of the tunnel are covered in [Connect a workstation MCP server](/tutorials/connect-a-workstation-server).
Then click **Test connection**. The first connection can take a while, because `uvx` downloads the proxy on first run — give it time. On success, MCP Manager discovers the AWS tools and takes you to the instance's **Features** page.
You should see the AWS tools (all prefixed `aws___`) on the **Features** page. The AWS MCP Server is now a server you can assign to a [gateway](https://app.mcpmanager.ai/settings/gateways), the same as any other.
## What the AWS MCP Server gives your agent
Once connected, the server exposes a deliberately small, fixed set of tools (all prefixed `aws___`), in two groups:
* **Knowledge tools** — `search_documentation`, `read_documentation`, `retrieve_skill`, `recommend`, `list_regions`, and `get_regional_availability`. These retrieve **current** AWS documentation and best-practice "skills" at query time, so an agent isn't limited to what its training data knew about newer services.
* **API tools** — `call_aws` (run most of the 15,000+ AWS API operations with your IAM credentials), `run_script` (execute Python in a sandbox that inherits your IAM permissions but has **no** network or local-filesystem access), `get_presigned_url`, and `get_tasks` (poll long-running calls).
Because MCP Manager namespaces an upstream server's tools by the server's display name, these will also carry your server's prefix when an AI client lists them. The full, authoritative tool reference is [Understanding the MCP Server tools](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/understanding-mcp-server-tools.html).
## Per-developer or centralized access
SigV4 means AWS credentials must live wherever the proxy runs, which shapes how you roll this out:
* **Per-developer (recommended).** Each developer runs the proxy as a workstation server with their **own** IAM identity. Every AWS call is signed with — and attributable to — that person, and their credentials never leave their machine. This is the path above, and it's the cleanest fit for short-lived `aws login` sessions.
* **Centralized / shared.** To put a single shared AWS identity behind a gateway for a team, run the proxy as a [Managed server](/mcp-gateway-concepts/mcp-servers/managed) in infrastructure you provide. There you must supply AWS credentials to the hosting environment — strongly prefer an **IAM role attached to the host** over long-lived access keys, and scope it tightly, because a shared, long-lived credential is a larger blast radius than a per-developer session. There's no way to centralize the connection without centralizing (and then securing) a credential.
Working across multiple AWS accounts? Configure several CLI profiles and pass them to the proxy (`--profile` or the `AWS_MCP_PROXY_PROFILES`
environment variable). The proxy then adds an optional `aws_profile` parameter to its auth-requiring tools so the agent can route a call through a
specific account. See AWS's [Multi-profile support](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/multi-account-access.html).
## Gotchas & things to keep in mind
* **`ExpiredTokenException` is the most common error.** Default session tokens are short-lived (often one hour). Refresh your credentials — `aws login` renews automatically — and then re-run **Test connection** (or restart the proxy) so it picks them up.
* **A `-32602 Invalid request parameters` error often means expired credentials, not a bad request.** Some clients surface the proxy's `LoginRefreshRequired` as a generic JSON-RPC `-32602`, sending you chasing a malformed-request problem that's really an auth one ([proxy issue #304](https://github.com/aws/mcp-proxy-for-aws/issues/304)). If a previously working connection starts failing this way, re-run `aws login` first.
* **Set `--metadata AWS_REGION=…` deliberately.** Without it, operations run in `us-east-1` regardless of which endpoint you connected to — the single most common region surprise.
* **Run the proxy command where your credentials are.** The *Start your MCP server* command launches the proxy in that terminal; if it can't see your `aws login` session or `AWS_PROFILE`, signing fails. (See [Where your AWS credentials live](#where-your-aws-credentials-live).)
* **Remove conflicting older AWS MCP servers from your AI client.** If you previously used the `aws-api-mcp-server` or `aws-knowledge-mcp-server`, AWS recommends removing them so overlapping tools don't 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`), so write your queries accordingly. MCP Manager's own [Logs](https://app.mcpmanager.ai/settings/logging/logs) capture the same calls as they pass through the gateway, tied to the person who made them.
## Further reading
The mechanism behind this guide — the encrypted tunnel, the local router, and the governance model.
The hands-on walkthrough of the workstation flow, including the two generated commands in full.
How MCP Manager detects a server's authentication type, and how to find other servers.
How MCP Manager authenticates to servers, and how identities are stored and shared.
## External sources
AWS's authoritative setup guide — credentials, regional endpoints, client configuration, and troubleshooting.
The open-source SigV4 proxy you launch locally, with the current version and configuration options.
The full reference for the `aws___` knowledge and API tools the server exposes.
How IAM authorizes the server, and how to use condition keys to restrict agent actions.
Configure multiple AWS accounts and route individual calls with the `aws_profile` parameter.
AWS's GA announcement — the design, the tools, and the IAM/SigV4 authentication model.