MCP Authentication

The MCP server uses a separate OAuth 2.0 authorization server at https://mcp.dynamosql.com. This is distinct from the REST API token endpoint at https://api.dynamosql.com/v1/auth/token.

Use the same API client credentials, but not the same bearer token. The REST API accessToken from https://api.dynamosql.com/v1/auth/token is not accepted on POST /mcp. The MCP server only accepts bearer tokens minted by https://mcp.dynamosql.com/token.

Supported flows

Flow	Caller type	Notes
`authorization_code` + PKCE (`S256`)	Human users in OAuth-capable MCP clients	Browser login through `auth.dynamosql.com`, explicit DynamoSQL consent, rotating refresh tokens
`refresh_token`	Human users in OAuth-capable MCP clients	Used to renew MCP access tokens after interactive sign-in
`client_credentials`	API clients and automation	Uses API client ID/secret from the DynamoSQL portal

Interactive browser login supports pre-registered clients, Client ID Metadata Documents (CIMD), and Dynamic Client Registration (DCR) for public interactive clients. DynamoSQL always validates the final redirect_uri and shows a consent screen before issuing the MCP auth code.

OAuth 2.0 discovery

MCP clients that support OAuth discovery can find the authorization and token endpoints automatically:

Endpoint	URL
Protected resource metadata	`https://mcp.dynamosql.com/.well-known/oauth-protected-resource`
Authorization server metadata	`https://mcp.dynamosql.com/.well-known/oauth-authorization-server`

The protected resource metadata response:

{
  "resource": "https://mcp.dynamosql.com/mcp",
  "authorization_servers": ["https://mcp.dynamosql.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["query", "schemas:read"]
}

The authorization server metadata response:

{
  "issuer": "https://mcp.dynamosql.com",
  "authorization_endpoint": "https://mcp.dynamosql.com/authorize",
  "token_endpoint": "https://mcp.dynamosql.com/token",
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "client_credentials"
  ],
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_basic",
    "client_secret_post"
  ],
  "client_id_metadata_document_supported": true,
  "registration_endpoint": "https://mcp.dynamosql.com/register",
  "scopes_supported": ["query", "schemas:read"]
}

OAuth-capable MCP clients use a standard OAuth authorization-code flow with PKCE:

The MCP client sends the user to https://mcp.dynamosql.com/authorize. Clients can include prompt=login to force a fresh Hosted UI sign-in and avoid silently reusing an existing browser session.
DynamoSQL resolves the client from pre-registration, CIMD, or DCR, then redirects the browser to the DynamoSQL Hosted UI at auth.dynamosql.com.
The user signs in with their DynamoSQL portal account.
DynamoSQL exchanges the Cognito code server-side and shows a first-party consent page.
After approval, DynamoSQL returns a one-time MCP authorization code to the MCP client.
The MCP client exchanges that code at POST /token.
DynamoSQL returns:
- an MCP access_token
- a rotating refresh_token

The resulting bearer token is an MCP token minted by DynamoSQL. It is not a raw Cognito access token or ID token.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "kQ7JYf...",
  "scope": "query schemas:read"
}

API client authentication

Use this flow for automation, service accounts, or MCP clients that only support static bearer tokens.

Using HTTP Basic authentication (recommended)

curl -X POST https://mcp.dynamosql.com/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=query%20schemas:read"

Using form body credentials

curl -X POST https://mcp.dynamosql.com/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=query%20schemas:read"

Token response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "query schemas:read"
}

Field	Description
`access_token`	Bearer token for MCP requests
`token_type`	Always `Bearer`
`expires_in`	Token lifetime in seconds (600 = 10 minutes)
`scope`	Granted scopes (space-delimited)
`refresh_token`	Present only for interactive browser-login flows

Scopes

The scope parameter is optional. If omitted, the issued token includes all MCP-supported scopes allowed for that principal.

Scope	Enables
`query`	`run_sql` tool
`schemas:read`	`list_tables` and `describe_table` tools

The MCP surface only recognizes query and schemas:read. Other portal or API-client scopes are ignored for MCP token issuance.

Using the bearer token

Include the token in the Authorization header on POST /mcp requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

When the token is missing or invalid, the server returns 401 with a WWW-Authenticate challenge header pointing to the protected resource metadata URL.

Token errors

HTTP status	`error` code	Description
400	`invalid_grant`	Authorization code or refresh token is invalid, expired, replayed, or does not match the client / redirect URI / PKCE verifier
400	`invalid_client_metadata`	CIMD document or DCR payload is invalid
400	`invalid_request`	Required OAuth parameters are missing or malformed
400	`invalid_scope`	Requested scope exceeds the principal’s allowed MCP scopes
400	`unsupported_grant_type`	Grant type is not supported by DynamoSQL
401	`invalid_client`	Wrong API client credentials or inactive API client
429	`temporarily_unavailable`	Authentication service rate limited
500	`server_error`	Internal failure

Token lifecycle

MCP access tokens expire after 10 minutes (expires_in: 600)
Interactive browser-login sessions receive a rotating refresh token with a 12-hour default lifetime
API-client client_credentials tokens do not receive refresh tokens
MCP clients that support OAuth discovery and refresh-token handling can renew access tokens automatically
For static bearer-token configurations, request a new token when the current one expires

Dynamic Client Registration

Public interactive clients that do not use CIMD can register dynamically at POST /register. Requirements:

client_name
redirect_uris
grant_types including authorization_code
response_types including code
token_endpoint_auth_method = none

Redirect URI rules:

https://... is always allowed
loopback HTTP is allowed only for http://127.0.0.1/... and http://localhost/...
custom URI schemes and non-loopback plain HTTP are rejected

DCR is public-client-only in this release. DynamoSQL does not issue client secrets for DCR clients and does not support RFC 7592 registration-management APIs yet.

Get Started

Guides

MCP Server

API Reference

SQL Reference

Changelog

MCP Authentication

Supported flows

OAuth 2.0 discovery

API client authentication

Using HTTP Basic authentication (recommended)

Using form body credentials

Token response

Scopes

Using the bearer token

Token errors

Token lifecycle

Dynamic Client Registration

​Supported flows

​OAuth 2.0 discovery

​Human-user browser login

​Example token response after interactive login

​API client authentication

​Using HTTP Basic authentication (recommended)

​Using form body credentials

​Token response

​Scopes

​Using the bearer token

​Token errors

​Token lifecycle

​Dynamic Client Registration

Supported flows

OAuth 2.0 discovery

Human-user browser login

Example token response after interactive login

API client authentication

Using HTTP Basic authentication (recommended)

Using form body credentials

Token response

Scopes

Using the bearer token

Token errors

Token lifecycle

Dynamic Client Registration