MCP Quickstart

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

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.

Open the API clients page in the DynamoSQL portal
Click Create API client
Enter a label (for example, Claude Desktop)
Select the query and schemas:read scopes
Click Create API client
Copy the Client ID and Client Secret — the secret is shown only once

Step 2 — Configure your MCP client

Recommended for OAuth-capable clients

Codex

If your Codex build supports remote MCP OAuth discovery:

Add the remote server URL https://mcp.dynamosql.com/mcp
Let Codex discover the OAuth metadata automatically
When Codex prompts for authentication, choose the browser sign-in flow
Sign in with your DynamoSQL portal account on auth.dynamosql.com
Review the DynamoSQL consent screen and approve the requested scopes
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:

Use https://mcp.dynamosql.com/mcp as the server URL
Let the client discover:
- https://mcp.dynamosql.com/.well-known/oauth-protected-resource
- https://mcp.dynamosql.com/.well-known/oauth-authorization-server
Complete browser sign-in when prompted
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"

// Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// or %APPDATA%\\Claude\\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "dynamosql": {
      "url": "https://mcp.dynamosql.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

// Add to .mcp.json in your project root or ~/.claude/.mcp.json globally
{
  "mcpServers": {
    "dynamosql": {
      "type": "url",
      "url": "https://mcp.dynamosql.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

// Add to Cursor MCP settings (Settings > MCP Servers > Add)
{
  "mcpServers": {
    "dynamosql": {
      "url": "https://mcp.dynamosql.com/mcp",
      "headers": {
        "Authorization": "Bearer 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

Symptom	Likely cause	Fix
`invalid_client` error on token request	Wrong client ID or secret	Verify credentials in the portal; rotate the secret if unsure
`invalid_scope` error on token request	Requested scope not granted to client	Check that the API client has `query` and `schemas:read` scopes in the portal
`invalid_grant` during browser login	Authorization code, redirect URI, PKCE verifier, or refresh token is invalid or expired	Restart the login flow and ensure the MCP client uses the exact registered redirect URI
Browser login does not start	MCP client is not approved for interactive login	Use API client credentials instead or contact DynamoSQL support
401 on MCP requests	Expired or missing bearer token	Sign in again or obtain a fresh token from `/token`
No tools listed	Token missing required scopes	Ensure the token was issued with both `query` and `schemas:read`
”Table not found” error	Wrong schema or table name	Call `list_tables` first to discover available tables

Next steps

MCP Authentication — full OAuth flow details and token lifecycle
Tools and Resources — complete reference for all MCP tools, resources, and prompts
SQL Reference — supported SQL syntax
SQL Limitations — unsupported features to be aware of

Get Started

Guides

MCP Server

API Reference

SQL Reference

Changelog

Prerequisites

Step 1 — Choose an authentication mode

Option B — API client credentials

Step 2 — Configure your MCP client

Recommended for OAuth-capable clients

Codex

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

Fallback for static bearer-token clients

Obtaining a static bearer token

Step 3 — Verify the connection

Troubleshooting

Next steps

​Prerequisites

​Step 1 — Choose an authentication mode

​Option A — Browser login for human users

​Option B — API client credentials

​Step 2 — Configure your MCP client

​Recommended for OAuth-capable clients

​Codex

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

​Fallback for static bearer-token clients

​Obtaining a static bearer token

​Step 3 — Verify the connection

​Troubleshooting

​Next steps

Prerequisites

Step 1 — Choose an authentication mode

Option A — Browser login for human users

Option B — API client credentials

Step 2 — Configure your MCP client

Recommended for OAuth-capable clients

Codex

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

Fallback for static bearer-token clients

Obtaining a static bearer token

Step 3 — Verify the connection

Troubleshooting

Next steps