Tools and Resources

​

Tools

Tools are the primary way AI assistants interact with your DynamoDB data. Each tool is only available when the bearer token includes the required scope. Bearer tokens may come from either:

• interactive browser login (authorization_code + PKCE + consent + refresh token)
• API client credentials (client_credentials)

​

list_tables

Lists tables available in one schema for the authenticated tenant. Required scope: schemas:read Arguments: Response fields: Example interaction:

User: “What tables do I have?” Assistant calls: list_tables with {} Result: 3 tables — orders, customers, products in schema east

---

​

describe_table

Returns column, index, and type metadata for a single table. Required scope: schemas:read Arguments: Response fields: Example interaction:

User: “What columns does the orders table have?” Assistant calls: describe_table with { "table_name": "orders" } Result: Columns order_id (S, primary key), customer_id (S), total (N), status (S), order_date (S)

---

​

run_sql

Executes a read-only SQL query against the authenticated tenant’s data. Required scope: query Arguments: Response fields: Error cases: Example interaction:

User: “Show me the top 5 customers by total spend” Assistant calls: run_sql with:

{
  "sql": "SELECT customer_id, SUM(total) AS total_spend FROM east.orders GROUP BY customer_id ORDER BY total_spend DESC LIMIT 5",
  "max_rows": 5
}

Result: 5 rows with customer_id and total_spend columns

---

​

Resources

Resources provide static documentation that AI assistants can read for context about DynamoSQL’s SQL capabilities.

​

docs://sql-overview

High-level summary of supported SQL features including SELECT, JOINs, CTEs, aggregations, subqueries, set operations, and functions. Includes an example query.

​

docs://sql-limitations

List of unsupported features including write operations, DDL, window functions, recursive CTEs, CAST/CONVERT, and behavioral notes about pagination and string escaping.

---

​

Prompts

Prompts are guided workflows that help AI assistants follow best practices when exploring data or writing queries.

​

explore-data

Guides the AI through schema discovery before querying. Arguments: Behavior: Instructs the AI to call list_tables first, then describe_table on relevant tables, and keep queries bounded with LIMIT.

​

write-query

Helps the AI write a read-only query that respects DynamoSQL limitations. Arguments: Behavior: Instructs the AI to use only SELECT syntax, avoid unsupported features (INSERT, UPDATE, DELETE, DDL, window functions, CAST), and reference the SQL limitations documentation when needed.

---

​

Metadata refresh modes

The refresh parameter on list_tables and describe_table controls how table metadata is loaded: Use force when you know table structure has recently changed. Use skip to avoid refresh latency when metadata accuracy is not critical.

​

Interactive registration notes

For browser-based login, the MCP server can recognize interactive clients through:

• exact pre-registration in DynamoSQL
• Client ID Metadata Documents (CIMD)
• Dynamic Client Registration (DCR) for public interactive clients

CIMD notes:

• client_id must be an HTTPS URL with a path
• DynamoSQL fetches the metadata document server-side
• the metadata document must allow authorization_code, code, and token_endpoint_auth_method = none

DCR notes:

• POST /register returns an opaque client_id
• DCR clients are public clients only in this release
• loopback HTTP redirect URIs are allowed only for 127.0.0.1 and localhost