awslabs / awslabs/agentcore-samples
Add tutorial: OAuth-protected MCP server targets with PKCE and agent-mediated auth
- Dominant language
- Python
- Stars
- 3.4k
- Forks
- 1.3k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 30
Description
## Description
Add a new Gateway tutorial demonstrating how to connect AgentCore Gateway to OAuth-protected MCP servers using Authorization Code Grant (3LO) for outbound authentication.
## What this covers
- **Inbound auth**: Two methods — PKCE (browser login, no client secret) and agent-mediated (AgentCore Identity federated token via `USER_FEDERATION`)
- **Outbound auth**: 3LO flow with GitHub MCP server as the example target
- **Gateway config**: `allowedClients` authorizer with Cognito as the IdP
- **Session binding**: `complete-resource-token-auth` callback handling for 3LO consent
- **Multi-provider support**: Gateway configuration examples for Cognito, Okta, Microsoft Entra, and Auth0
## Proposed files
01-tutorials/02-AgentCore-gateway/17-oauth-protected-mcp-server-targets/
├── 01-pkce-github.ipynb # PKCE flow (no client secret)
├── 02-agent-mediated-github.ipynb # Agent-mediated flow (AgentCore Identity)
├── oauth2_callback_server.py # Shared callback server for 3LO binding
├── requirements.txt
└── README.md
## Related
- Extends `13-outbound-auth-code-grant` (LinkedIn/OpenAPI) to cover MCP server targets
- Demonstrates both PKCE and agent-mediated inbound auth patterns
Contributor guide
Research direction
Start by reviewing the existing 13-outbound-auth-code-grant tutorial and the proposed directory under 01-tutorials/02-AgentCore-gateway/17-oauth-protected-mcp-server-targets/. Add the two notebooks, shared oauth2_callback_server.py, requirements.txt, and README.md covering PKCE, agent-mediated auth, 3LO binding, and the listed identity providers. Done means the tutorial clearly demonstrates both inbound patterns and GitHub MCP outbound authentication.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, github, python
- Domain
- authentication, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100