Datadata Manual

datadata-manual is the interactive operations manual for the Datadata platform, calling platform capabilities directly through the MCP (Model Context Protocol) Server. AI agents can search datasources, execute queries, and manage Data Spaces as if calling local tools.

For generating standalone Python scripts (crawlers/ETL/batch), use the datadata-rest-api skill. MCP is designed for chat interaction and is not suitable for generating independently runnable script files.

Installation

npx skills add datadata-team/datadata-skills

Once installed, agents can interact with Datadata through the following MCP tools.

MCP Endpoint

https://www.datadata.com/api/mcp/v1

Authentication

OAuth 2.0 (Recommended)

When configuring the MCP client, choose OAuth. The browser will redirect to Datadata for authorization. This is the most standard and convenient method, supported by Claude Desktop, VS Code, Cursor, Windsurf, Claude Code, and other MCP clients.

API Key Authentication

You can also authenticate via API Key:

1. Log in to datadata.com → Settings → API Keys
2. Create a new key and select the required permissions
3. Configure it in your MCP client

Recommended Permissions:

Permission	Purpose
queries:execute-adhoc	Run SQL/DQL queries
executions:get	Retrieve query results
datasources:read	Read datasource information
datasources:scan	Scan datasource structure
datasources:replace-file	Replace datasource files
data-spaces:write	Manage tables and data in Data Spaces

MCP Tools

Datasource Discovery & Metadata

Tool	Purpose	Key Parameters
search-datasource	Search for datasources	search — username or keyword
get-datasource-info	Get datasource metadata	datasourceId
list-tables	List tables and views	datasourceId, schemaName (optional)
describe-table	Get table column structure (cached metadata with comments)	datasourceId, schemaName, tableName
scan-datasource	Trigger async schema scan	datasourceId
set-table-comment	Set table/column comments	datasourceId, schemaName, tableName

Data Querying

Tool	Purpose
execute-adhoc	Execute SQL/DQL queries, returns execution ID and result download link

Data Spaces Management

Tool	Purpose	Key Parameters
dataspace-create	Create a Data Space (a dataspace-type datasource)	name, displayName, description, visibility, tags (optional)
dataspace-execute-sql	Run arbitrary DuckDB SQL in a Data Space (create / write / alter / drop)	datasourceId, sql, args (optional)

A Data Space is an independent DuckDB database; all schema and data changes are done with SQL via dataspace-execute-sql. After changing the schema, call scan-datasource to refresh metadata.

Query Engine & SQL Writing

Engine Selection

• Default to duckdb engine
• Switch to clickhouse only for ClickHouse datasources
• DuckDB supports cross-datasource JOINs; ClickHouse does not

Datasource Binding

Bind datasources via the datasources parameter, format:

["DATASOURCE_ID:ATTACH_ALIAS"]

Reference tables in SQL by alias, not datasource ID.

Table Naming Conventions

Data Spaces (dataspace type):

"{attachAlias}".main."{tableName}"

where main is DuckDB's fixed schema and attachAlias is the mount alias (conventionally the datasource name).

Database datasources (MySQL, PostgreSQL, etc.):

attachAlias.schemaName.tableName

File datasources (CSV, JSON, Parquet, etc.):

memory.main.attachAlias

Data Spaces

Data Spaces are a capability exclusive to dataspace-type datasources: use dataspace-create to create a Data Space, and dataspace-execute-sql to run arbitrary DuckDB SQL that manages its tables and data.

Read / write separation: writes (create / alter tables, write data) go through dataspace-execute-sql (synchronous); reads go through execute-adhoc (mounting the Data Space as a read-only datasource).

Full Workflow

dataspace-create (create the Data Space)
  → dataspace-execute-sql (CREATE TABLE)
  → dataspace-execute-sql (INSERT)
  → execute-adhoc (mount the Data Space and query to verify)
  → dataspace-execute-sql (DROP TABLE to clean up)

Result Handling

execute-adhoc returns an execution ID and a result download link (NDJSON/CSV). Agents download to local storage using curl for preview.

Do not read full large datasets directly into context.

Configuration Example

{
  "mcpServers": {
    "datadata": {
      "command": "npx",
      "args": ["-y", "@datadata/mcp-server"],
      "env": {
        "DATADATA_API_KEY": "ak_xxxxxxxxxxxxxxxx"
      }
    }
  }
}