> ## 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.

# Overview

> Connect AI assistants to your DynamoDB data with the DynamoSQL MCP server.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants connect to external data sources and tools. DynamoSQL provides an MCP server that gives AI assistants direct access to your DynamoDB data through schema discovery and read-only SQL execution.

## What the DynamoSQL MCP server provides

The MCP server exposes three capabilities:

| Capability    | Description                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Tools**     | `list_tables`, `describe_table`, and `run_sql` -- let the AI discover schemas, inspect table structures, and execute read-only SQL |
| **Resources** | Bundled documentation covering supported SQL syntax and known limitations                                                          |
| **Prompts**   | Guided workflows for exploring data and writing queries                                                                            |

## When to use MCP vs. the REST API

| Use case                                                       | Recommended                                     |
| -------------------------------------------------------------- | ----------------------------------------------- |
| AI assistant exploring and querying your data conversationally | **MCP server**                                  |
| Application or script executing SQL programmatically           | **REST API** ([Quickstart](/guides/quickstart)) |

Both use the same API client credentials created in the [DynamoSQL portal](https://portal.dynamosql.com/api-clients).

## Server URL

```
https://mcp.dynamosql.com/mcp
```

## Authentication

The MCP server supports two authentication modes:

| Caller type                               | Flow                                                                      | Best for                                                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Human user in an OAuth-capable MCP client | OAuth 2.0 `authorization_code` + PKCE (`S256`) + rotating `refresh_token` | Codex and other MCP clients that can open a browser for sign-in and support pre-registration, CIMD, or DCR |
| API client / automation                   | OAuth 2.0 `client_credentials`                                            | Static MCP configurations, service accounts, and automation                                                |

In both cases, the MCP bearer token is separate from the REST API bearer token. See [MCP Authentication](/mcp/authentication) for details.

<Note>
  Interactive browser login supports three client-registration paths: exact pre-registration for known clients, Client ID Metadata Documents (CIMD), and Dynamic Client Registration (DCR) for public interactive clients. Every interactive login shows a DynamoSQL consent screen before the auth code is issued.
</Note>

## Scopes

Scopes control which tools are available to the AI assistant:

| Scope          | Tools enabled                   |
| -------------- | ------------------------------- |
| `query`        | `run_sql`                       |
| `schemas:read` | `list_tables`, `describe_table` |

Grant both scopes for full access. If a scope is not granted, the corresponding tools are not advertised to the AI assistant.

## Behavioral notes

* The MCP server is **read-only**. Only `SELECT` and `WITH` statements are accepted.
* Query results are capped at **1000 rows** (default 100).
* Table listings are capped at **200 tables**.
* MCP request handling is **stateless**, but interactive OAuth uses short-lived server-side state for consent, authorization codes, refresh-token rotation, CIMD caching, and DCR registration.
* Access tokens expire after **10 minutes**.
* Interactive browser login issues rotating refresh tokens with a **12-hour** default session lifetime.

## Next steps

* [MCP Quickstart](/mcp/quickstart) -- connect your AI assistant in 5 minutes
* [MCP Authentication](/mcp/authentication) -- OAuth flow details
* [Tools and Resources](/mcp/tools-and-resources) -- complete reference for all tools, resources, and prompts