MCP Server
Connect AI coding agents to DataTalk through the Model Context Protocol
DataTalk exposes its public API as an MCP server, so AI agents like Claude Code, Codex, Cursor, and Gemini CLI can browse your databases, explore schemas, and turn natural-language questions into SQL.
Endpoint
The server uses the streamable HTTP transport and lives on your DataTalk host:
https://<your-datatalk-host>/api/mcpIn the DataTalk app, Settings > API > MCP shows setup snippets prefilled with your instance URL.
Authentication
The MCP server uses the same API keys as the REST API: pass your dt_ key as a Bearer token in the Authorization header. See Authentication for how to create one. API access must be enabled on your plan.
Setup
Claude Code
claude mcp add --transport http datatalk https://<your-datatalk-host>/api/mcp \
--header "Authorization: Bearer dt_your_api_key"Codex
[mcp_servers.datatalk]
url = "https://<your-datatalk-host>/api/mcp"
bearer_token_env_var = "DATATALK_API_KEY"Export DATATALK_API_KEY with your key in the environment before launching Codex.
Cursor
{
"mcpServers": {
"datatalk": {
"url": "https://<your-datatalk-host>/api/mcp",
"headers": {
"Authorization": "Bearer dt_your_api_key"
}
}
}
}Gemini CLI
{
"mcpServers": {
"datatalk": {
"httpUrl": "https://<your-datatalk-host>/api/mcp",
"headers": {
"Authorization": "Bearer dt_your_api_key"
}
}
}
}Tools
The typical flow: list_databases to find the target database, optionally list_tables / get_table to explore the schema, generate_query to turn a prompt into SQL, then get_artifact_data to execute it and read the rows.
list_databases
List the connected databases the authenticated user can query (paginated with limit/offset). Returns each database's id, name, short description, engine type, and table count. Start here: the returned id is the databaseId required by the other tools.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Databases to return, 1–100 (default 50) |
offset | integer | no | Items to skip (default 0) |
get_database
Get details of a single database, including its description and metadata.
| Parameter | Type | Required | Description |
|---|---|---|---|
databaseId | string (UUID) | yes | Database ID from list_databases |
list_tables
List the tables of a database (paginated with limit/offset). Use include to enrich results with column structure and/or description metadata. Useful for exploring a schema before calling generate_query.
| Parameter | Type | Required | Description |
|---|---|---|---|
databaseId | string (UUID) | yes | Database ID from list_databases |
limit | integer | no | Tables to return, 1–1000 (default 200) |
offset | integer | no | Items to skip (default 0) |
include | string[] | no | Extra data to include: "structure" (columns and relationships), "description" (description, context and tags) |
get_table
Get details for a single table (tableId from list_tables). Use include to enrich with column structure and/or description metadata.
| Parameter | Type | Required | Description |
|---|---|---|---|
databaseId | string (UUID) | yes | Database ID from list_databases |
tableId | string (UUID) | yes | Table ID from list_tables |
include | string[] | no | Extra data to include: "structure" (columns and relationships), "description" (description, context and tags) |
list_artifacts
List artifacts owned by the authenticated user, newest first. An artifact is a saved output produced by DataTalk (kind: sql, chart, dashboard, or report). Pass the nextCursor value from the previous response as cursor to fetch the next page.
| Parameter | Type | Required | Description |
|---|---|---|---|
pageSize | integer | no | Artifacts per page, 1–100 (default 20) |
cursor | string | no | nextCursor from the previous response; omit for the first page |
get_artifact
Get a single artifact's kind, title, description, and content. For sql artifacts, use get_artifact_data to execute the query and fetch rows.
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string (UUID) | yes | Artifact ID from list_artifacts or generate_query |
get_artifact_data
Execute the saved SQL query of a sql-kind artifact against its database and return the result rows (paginated). Works with an artifactId from list_artifacts or one just created by generate_query. Fails for non-sql artifact kinds.
| Parameter | Type | Required | Description |
|---|---|---|---|
artifactId | string (UUID) | yes | ID of a sql artifact from list_artifacts or generate_query |
page | integer | no | Page number, from 1 (default 1) |
pageSize | integer | no | Rows per page, 1–1000 (default 20) |
generate_query
Generate a SQL query from a natural-language prompt against a connected database. The query is not executed: it is saved as a sql-kind artifact and returned. Pass the returned artifactId to get_artifact_data to execute it and fetch the result rows.
| Parameter | Type | Required | Description |
|---|---|---|---|
databaseId | string (UUID) | yes | Database ID from list_databases |
prompt | string | yes | What the query should answer, in natural language (max 10,000 characters) |
timezone | string | no | IANA time zone for relative dates such as "today" or "last month", e.g. Europe/Rome (default UTC) |
The result lists the created artifacts, each with artifactId, title, sqlQuery and outputType (scalar or rows). If no query can be generated, the tool returns an error with the AI's explanation. The AI reads query results while working only if data access is enabled for both the tenant and the database.
Rate Limits
MCP requests are limited to 60 requests per minute per API key, independently from the REST API quota. Over-limit requests receive a 429 response with a Retry-After header.
Errors
Tool failures (not found, no access, invalid parameters, tenant spending limit reached, query errors) are returned as tool results with isError: true and a text message, not as HTTP errors. The message starts with the same code as the REST API, for example QUERY_TIMEOUT: The query took too long and was stopped by the database. Authentication failures are HTTP responses with the same codes as the REST API (see Authentication): 401 for a missing, malformed, unknown or expired key (or one whose user no longer exists), 403 when the key's tenant no longer exists, its license is invalid, or its plan has no API access. The body says why:
{
"error": "insufficient_scope",
"error_description": "API access is not available for your plan",
"code": "API_ACCESS_DENIED"
}Rate limits are HTTP 429.