aws / aws/agent-toolkit-for-aws
Use OAuth-based MCP config for AWS MCP Server in plugins (remove hard dependency on uvx/mcp-proxy-for-aws)
- Dominant language
- Python
- Stars
- 2.6k
- Forks
- 306
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 51
Description
## Problem
The `aws-core` and `aws-data-analytics` plugins ship an MCP config that depends on `uvx` to launch `mcp-proxy-for-aws`:
```json
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws@1.6.3",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--skip-auth",
"--metadata",
"INSTALL_SOURCE=agent-toolkit"
]
}
}
}
```
If `uv`/`uvx` is not installed, the proxy is never pulled down and the server silently fails to start. This is a poor first-run experience for customers without `uv` and depending on the client its not clear that the lack of `uv` caused the issue.
## Context
The AWS MCP Server now supports OAuth as a first-class authentication method:
- Blog: [Introducing OAuth Support for AWS MCP Server](https://aws.amazon.com/blogs/security/introducing-oauth-support-for-aws-mcp-server/)
- Docs: [Setting up the AWS MCP Server](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) — documents OAuth as "Option A (simple)" and SigV4 + proxy as "Option B (advanced)"
With OAuth, clients connect directly to `https://aws-mcp.us-east-1.api.aws/mcp` over HTTP transport — no `uv`, no AWS CLI, no local credentials needed to get started. Unauthenticated tools (e.g. documentation search) work before the OAuth sign-in is even completed, so the first-run experience gives users access to unauth tools (docs, skills, etc)
However, neither the toolkit README nor the plugin MCP configs mention OAuth today, and the blog post doesn't cover how to use it with the toolkit plugins.
## Proposal
Switch the plugin MCP config for clients that support the OAuth flow to a direct HTTP config, and keep the `uvx` proxy config for generic/other clients. The toolkit already customizes MCP config per client, and other plugins in this repo already use HTTP transport (`aws-agents`, `aws-agents-for-devsecops`), so this is expressible today. Roughly:
```json
{
"mcpServers": {
"aws-mcp": {
"type": "http",
"url": "https://aws-mcp.us-east-1.api.aws/mcp"
}
}
}
```
Per the docs, Claude Code and Kiro CLI support OAuth with the plain endpoint URL; Cursor, Claude Desktop, Kiro IDE, Gemini CLI, and Codex need `?oauth=initialize` appended.
## Open questions
1. **Install-source attribution** — the proxy config passes `--metadata INSTALL_SOURCE=agent-toolkit`. Is there an equivalent for direct HTTP connections (header/query param), or do we accept losing attribution for OAuth installs?
2. **Feature gaps vs SigV4** — OAuth doesn't support multi-profile/cross-account switching or the proxy's `--read-only` mode. Do we default to OAuth and document SigV4 as the opt-in advanced path, or gate by client?
3. **Org restrictions** — some organizations restrict `signin:AuthorizeOAuth2Access` / `signin:CreateOAuth2Token`; those users need the SigV4 path. The README/troubleshooting docs should cover both.
4. **Docs** — regardless of the config change, the toolkit README should mention OAuth as an option and link to the setup guide, so users without `uv` have a documented escape hatch.
Contributor guide
Research direction
Compare the existing MCP configs for the aws-core and aws-data-analytics plugins with the HTTP configurations used by aws-agents and aws-agents-for-devsecops. Check how the toolkit customizes configs for Claude Code, Kiro CLI, Cursor, Claude Desktop, Gemini CLI, and Codex. Done means supported clients use the direct OAuth endpoint, generic clients retain the proxy path, and the toolkit README documents both options and their limitations.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100