DataTalk Docs

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/mcp

In 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

Terminal
claude mcp add --transport http datatalk https://<your-datatalk-host>/api/mcp \
  --header "Authorization: Bearer dt_your_api_key"

Codex

~/.codex/config.toml
[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

~/.cursor/mcp.json
{
  "mcpServers": {
    "datatalk": {
      "url": "https://<your-datatalk-host>/api/mcp",
      "headers": {
        "Authorization": "Bearer dt_your_api_key"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json
{
  "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.

ParameterTypeRequiredDescription
limitintegernoDatabases to return, 1–100 (default 50)
offsetintegernoItems to skip (default 0)

get_database

Get details of a single database, including its description and metadata.

ParameterTypeRequiredDescription
databaseIdstring (UUID)yesDatabase 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.

ParameterTypeRequiredDescription
databaseIdstring (UUID)yesDatabase ID from list_databases
limitintegernoTables to return, 1–1000 (default 200)
offsetintegernoItems to skip (default 0)
includestring[]noExtra 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.

ParameterTypeRequiredDescription
databaseIdstring (UUID)yesDatabase ID from list_databases
tableIdstring (UUID)yesTable ID from list_tables
includestring[]noExtra 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.

ParameterTypeRequiredDescription
pageSizeintegernoArtifacts per page, 1–100 (default 20)
cursorstringnonextCursor 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.

ParameterTypeRequiredDescription
artifactIdstring (UUID)yesArtifact 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.

ParameterTypeRequiredDescription
artifactIdstring (UUID)yesID of a sql artifact from list_artifacts or generate_query
pageintegernoPage number, from 1 (default 1)
pageSizeintegernoRows 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.

ParameterTypeRequiredDescription
databaseIdstring (UUID)yesDatabase ID from list_databases
promptstringyesWhat the query should answer, in natural language (max 10,000 characters)
timezonestringnoIANA 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.

On this page