Skip to main content

​
Prerequisites

When creating your API client, select both the query and schemas:read scopes for full MCP access.

​
Step 1 — Create an API client

  1. Open the API clients page in the DynamoSQL portal
  2. Click Create API client
  3. Enter a label (e.g., “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

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"

​
Other MCP clients

For any MCP client not listed above:
  • Use https://mcp.dynamosql.com/mcp as the remote MCP server URL
  • If the client supports OAuth discovery for remote MCP servers, point it at the server URL and let it discover:
    • https://mcp.dynamosql.com/.well-known/oauth-protected-resource
    • https://mcp.dynamosql.com/.well-known/oauth-authorization-server
  • If the client only supports static bearer tokens, mint a token from POST /token and send it as Authorization: Bearer <token>

​
Obtaining a bearer token

The MCP server uses its own OAuth token endpoint. Exchange your API client credentials for a 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.
MCP bearer tokens expire after 10 minutes. MCP clients that support OAuth 2.0 discovery will handle token refresh automatically. For clients that require a static token, you will need to refresh it manually.
MCP clients that support OAuth discovery for remote MCP servers can discover the token endpoint automatically via https://mcp.dynamosql.com/.well-known/oauth-protected-resource. In this case, you only need to provide the server URL and your client credentials — the MCP client handles token acquisition and refresh.

​
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
401 on MCP requestsExpired or missing bearer tokenObtain 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