OAuth 2.1

Connect Claude.ai and other OAuth 2.1 clients to your AWSYS account

The AWSYS MCP server supports OAuth 2.1 with PKCE as defined in the MCP 2025-06-18 authorization specification. This lets Claude.ai's connector UI (and other OAuth-capable MCP clients) connect to your account securely without manually copying an API key.

Existing awsys_... API keys continue to work alongside OAuth — nothing breaks for current integrations.

How It Works

The connection flow follows the standard OAuth 2.1 authorization code grant with PKCE:

1. Claude.ai discovers the authorization server via /.well-known/oauth-protected-resource
2. It registers itself via Dynamic Client Registration (or presents a Client ID Metadata Document)
3. You are redirected to AWSYS to log in and approve the connection
4. Claude.ai receives a short-lived access token (15 min) and a refresh token (24 h)
5. Subsequent MCP tool calls include the access token — no further prompts

Connecting via Claude.ai

1. In Claude.ai, go to Settings → Integrations → Add connector
2. Enter https://awsys.co/mcp as the server URL
3. Click Connect — Claude.ai auto-discovers the OAuth endpoints
4. You will be redirected to the AWSYS consent screen. Log in and click Allow Access
5. The connector is now active. All 54 MCP tools are available immediately

See the Help Center guide for step-by-step screenshots.

Discovery Endpoints

These are public JSON endpoints — no authentication required.

GET /.well-known/oauth-protected-resource

RFC 9728 Protected Resource Metadata. Points OAuth clients to the authorization server.

{
  "resource": "https://awsys.co/mcp",
  "authorization_servers": ["https://awsys.co"],
  "scopes_supported": ["mcp:tools", "mcp:resources", "offline_access"],
  "bearer_methods_supported": ["header"]
}

GET /.well-known/oauth-authorization-server

RFC 8414 Authorization Server Metadata. Lists all AS endpoints and capabilities.

{
  "issuer": "https://awsys.co",
  "authorization_endpoint": "https://awsys.co/oauth/authorize",
  "token_endpoint": "https://awsys.co/oauth/token",
  "registration_endpoint": "https://awsys.co/oauth/register",
  "revocation_endpoint": "https://awsys.co/oauth/revoke",
  "scopes_supported": ["mcp:tools", "mcp:resources", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"],
  "client_id_metadata_document_supported": true
}

Dynamic Client Registration

Clients that don't support CIMD can register via POST /oauth/register. Registration is rate-limited to 5 requests/minute/IP. Duplicate registrations (same redirect_uris) return the existing client_id.

Request

POST /oauth/register
Content-Type: application/json

{
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "client_name": "Claude.ai",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Response 201 Created

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_id_issued_at": 1749600000,
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

No client_secret is issued. All clients are public — PKCE is mandatory.

Authorization Code Flow

Step 1 — Authorization Request

GET /oauth/authorize
  ?response_type=code
  &client_id=550e8400-e29b-41d4-a716-446655440000
  &redirect_uri=https://claude.ai/api/mcp/auth_callback
  &scope=mcp:tools+offline_access
  &state=xyz
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &resource=https://awsys.co/mcp

code_challenge_method must be S256. plain is rejected. The resource parameter (RFC 8707) binds the issued tokens to this MCP server.

Step 2 — User Consent

AWSYS redirects you to a login + consent screen if you are not already signed in. After you click Allow Access, the browser redirects to your redirect_uri with a code parameter. Codes expire in 60 seconds and are single-use.

Step 3 — Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://claude.ai/api/mcp/auth_callback
&client_id=550e8400-e29b-41d4-a716-446655440000
&code_verifier=ORIGINAL_VERIFIER
&resource=https://awsys.co/mcp

Response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "mcp:tools offline_access",
  "refresh_token": "dBjftJeZ4CVP-mB92K27uhb..."
}

Scopes

Token Lifecycle

Token Refresh

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=CURRENT_REFRESH_TOKEN

Returns a new access_token and a new refresh_token. The old refresh token is immediately invalidated.

Token Revocation

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN_TO_REVOKE

Always returns 200 OK — revocation is best-effort and never reveals whether the token was valid.

Backward Compatibility

The MCP server accepts both OAuth access tokens and existing awsys_... API keys on the same Authorization: Bearer header. OAuth tokens are tried first (JWT validation, stateless); API key lookup runs only if JWT validation fails. No migration required for existing integrations.

Unauthenticated Request Response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://awsys.co/.well-known/oauth-protected-resource"

The WWW-Authenticate header is the entry point for automated OAuth discovery per RFC 9728.

Claude Code (CLI)

Claude Code uses the loopback redirect URI (http://localhost:PORT/callback). Any port is accepted. The flow is identical to the above — PKCE is required.