MCP Server

KUKAN provides a Model Context Protocol (MCP) compliant server endpoint. This enables Claude, ChatGPT, and other MCP-compatible AI agents to search and browse the data catalog.

Endpoint

POST /api/mcp

Operates in stateless mode using the Streamable HTTP transport.

Connecting

Claude Code / Claude Desktop

Add the following to your settings:

{
  "mcpServers": {
    "kukan": {
      "type": "url",
      "url": "https://your-kukan-site/api/mcp"
    }
  }
}

Testing with curl

curl -X POST https://your-kukan-site/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "0.1" }
    }
  }'

Available Tools

All tools are read-only. Access to private datasets is controlled based on the authenticated user’s permissions.

Tool	Description
`search_datasets`	Search datasets by keyword or natural language (hybrid search). Supports organization and tag filters
`get_dataset`	Get detailed dataset information including resource list
`get_resource`	Get resource (file) metadata and URL
`get_resource_schema`	Get a resource’s column schema (names, types, row count, stats). CSV/TSV only
`query_resource`	Run a read-only SQL query (SELECT only) over a resource’s data. CSV/TSV only
`list_organizations`	List organizations
`list_groups`	List groups (categories)
`list_tags`	List tags

Tool Details

search_datasets

Search the data catalog. Besides keywords, natural-language queries work too — semantically related datasets are included in the results (hybrid search).

Parameter	Type	Required	Description
`q`	string	Yes	Search keywords or a natural-language query
`organization`	string	No	Filter by organization name (slug)
`tags`	string[]	No	Filter by tag names
`semantic`	boolean	No	`false` limits results to keyword matches only (default: `true`)
`offset`	number	No	Number of results to skip (default: 0)
`limit`	number	No	Maximum results (default: 10, max: 50)

get_dataset

Get detailed information about a dataset.

Parameter	Type	Required	Description
`nameOrId`	string	Yes	Dataset name (slug) or UUID

get_resource

Get resource metadata. Returns the download URL for uploaded files.

Parameter	Type	Required	Description
`id`	string	Yes	Resource UUID

get_resource_schema

Get a resource’s column schema (names, types, nullability, row count, and min/max for numeric columns). Only CSV/TSV resources with a generated preview are queryable. The output names the query table data and includes an example query, so the agent can write SQL after inspecting the schema.

Parameter	Type	Required	Description
`id`	string	Yes	Resource UUID

query_resource

Run a read-only SQL query (SELECT / WITH only) over a resource’s data and return the result as a Markdown table. The data is exposed as a table named data. Use get_resource_schema first to learn the column names and types.

Parameter	Type	Required	Description
`id`	string	Yes	Resource UUID
`sql`	string	Yes	A single SELECT/WITH statement over the `data` table

Runs in a throwaway in-memory DuckDB instance with external access disabled and row/byte/time limits. Double-quote column names that contain non-ASCII characters. See the REST /resources/{id}/query endpoint for limits and error details.

list_organizations

Parameter	Type	Required	Description
`q`	string	No	Search by name
`offset`	number	No	Number of results to skip (default: 0)
`limit`	number	No	Maximum results (default: 20, max: 100)

list_groups

Parameter	Type	Required	Description
`q`	string	No	Search by name
`offset`	number	No	Number of results to skip (default: 0)
`limit`	number	No	Maximum results (default: 20, max: 100)

Parameter	Type	Required	Description
`q`	string	No	Search by name
`offset`	number	No	Number of results to skip (default: 0)
`limit`	number	No	Maximum results (default: 50, max: 200)

Authentication

The MCP endpoint integrates with KUKAN’s authentication system.

Unauthenticated: Access to public datasets only
Authenticated: Access to private datasets within your organizations
System admin: Access to all datasets

Include authentication headers in your request when authentication is needed.

Technical Specifications

Protocol: MCP (Model Context Protocol) 2025-03-26
Transport: Streamable HTTP
Mode: Stateless (no session management)
Response format: JSON-RPC 2.0