Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dynamosql.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

  • A DynamoSQL account with at least one schema configured
  • One of the following:
    • a DynamoSQL portal user account for browser-based sign-in
    • API client credentials from the DynamoSQL portal
For full MCP access, the resulting token should include both query and schemas:read.

​
Step 1 — Choose an authentication mode

​
Option A — Browser login for human users

Use this when your MCP client supports remote OAuth discovery and can identify itself through pre-registration, a Client ID Metadata Document (CIMD), or Dynamic Client Registration (DCR).
  • Recommended for Codex and other MCP clients that can open a browser for sign-in
  • Uses your DynamoSQL portal user account
  • Shows a DynamoSQL consent screen before the connection is approved
  • Automatically handles access-token refresh with rotating refresh tokens

​
Option B — API client credentials

Use this for automation, service accounts, or MCP clients that only support static bearer tokens.
  1. Open the API clients page in the DynamoSQL portal
  2. Click Create API client
  3. Enter a label (for example, Claude Desktop)
  4. Select the query and schemas:read scopes
  5. Click Create API client
  6. Copy the Client ID and Client Secret — the secret is shown only once

​
Step 2 — Configure your MCP client

​
Codex

If your Codex build supports remote MCP OAuth discovery:
  1. Add the remote server URL https://mcp.dynamosql.com/mcp
  2. Let Codex discover the OAuth metadata automatically
  3. When Codex prompts for authentication, choose the browser sign-in flow
  4. Sign in with your DynamoSQL portal account on auth.dynamosql.com
  5. Review the DynamoSQL consent screen and approve the requested scopes
  6. Return to Codex and complete the connection
If your Codex build only supports static bearer tokens, use the fallback configuration in the next section.

​
Claude Desktop / Claude Code / Cursor / other MCP clients with OAuth discovery

For any other MCP client that supports remote OAuth discovery:
  1. Use https://mcp.dynamosql.com/mcp as the server URL
  2. Let the client discover:
    • https://mcp.dynamosql.com/.well-known/oauth-protected-resource
    • https://mcp.dynamosql.com/.well-known/oauth-authorization-server
  3. Complete browser sign-in when prompted
  4. Review the DynamoSQL consent screen and approve the requested scopes
Interactive browser login requires one of these registration paths:
  • exact pre-registration in DynamoSQL
  • a valid HTTPS Client ID Metadata Document (CIMD)
  • successful Dynamic Client Registration (DCR)
If your MCP client supports none of those, use the static bearer-token flow below.

​
Fallback for static bearer-token clients

Choose the configuration for your AI assistant: 
# Add the remote MCP server once
codex mcp add dynamosql --url https://mcp.dynamosql.com/mcp \
  --bearer-token-env-var DYNAMOSQL_MCP_TOKEN

# Before launching Codex, export a fresh MCP bearer token
export DYNAMOSQL_MCP_TOKEN="YOUR_MCP_TOKEN"

​
Obtaining a static bearer token

If you are using API client credentials, exchange them for an MCP bearer token: 
curl -s -X POST https://mcp.dynamosql.com/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=query%20schemas:read"
The response contains your bearer token: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "query schemas:read"
}
Copy the access_token value and use it as YOUR_MCP_TOKEN in the configuration above.
Do not use the REST API accessToken from https://api.dynamosql.com/v1/auth/token as YOUR_MCP_TOKEN. The MCP server only accepts bearer tokens minted by https://mcp.dynamosql.com/token.
Static MCP bearer tokens expire after 10 minutes. Clients using browser-based OAuth can refresh automatically. Clients using a static token must request a new one when the current token expires.

​
Step 3 — Verify the connection

Once configured, ask your AI assistant to explore your data:
“List the tables in my DynamoDB schema”
The assistant should call list_tables and return your table names. Then try:
“Describe the orders table and show me the first 10 rows”

​
Troubleshooting

SymptomLikely causeFix
invalid_client error on token requestWrong client ID or secretVerify credentials in the portal; rotate the secret if unsure
invalid_scope error on token requestRequested scope not granted to clientCheck that the API client has query and schemas:read scopes in the portal
invalid_grant during browser loginAuthorization code, redirect URI, PKCE verifier, or refresh token is invalid or expiredRestart the login flow and ensure the MCP client uses the exact registered redirect URI
Browser login does not startMCP client is not approved for interactive loginUse API client credentials instead or contact DynamoSQL support
401 on MCP requestsExpired or missing bearer tokenSign in again or obtain a fresh token from /token
No tools listedToken missing required scopesEnsure the token was issued with both query and schemas:read
”Table not found” errorWrong schema or table nameCall list_tables first to discover available tables

​
Next steps