> ## 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.
# MCP Quickstart
> Connect your AI assistant to DynamoDB data in under 5 minutes.
## Prerequisites
* A DynamoSQL account with at least one [schema configured](/guides/iam-setup)
* One of the following:
* a DynamoSQL portal user account for browser-based sign-in
* API client credentials from the [DynamoSQL portal](https://portal.dynamosql.com/api-clients)
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](https://portal.dynamosql.com/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
### Recommended for OAuth-capable clients
#### 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:
```bash Codex theme={null}
# 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"
```
```json Claude Desktop theme={null}
// 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"
}
}
}
}
```
```json Claude Code (.mcp.json) theme={null}
// 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"
}
}
}
}
```
```json Cursor theme={null}
// 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:
```bash theme={null}
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:
```json theme={null}
{
"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](/mcp/authentication) -- full OAuth flow details and token lifecycle
* [Tools and Resources](/mcp/tools-and-resources) -- complete reference for all MCP tools, resources, and prompts
* [SQL Reference](/sql-reference/overview) -- supported SQL syntax
* [SQL Limitations](/sql-reference/limitations) -- unsupported features to be aware of