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. Supports organization and tag filters
get_dataset	Get detailed dataset information including resource list
get_resource	Get resource (file) metadata and URL
list_organizations	List organizations
list_groups	List groups (categories)
list_tags	List tags

Tool Details

search_datasets

Search the data catalog by keyword.

Parameter	Type	Required	Description
q	string	Yes	Search keywords
organization	string	No	Filter by organization name (slug)
tags	string[]	No	Filter by tag names
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

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)

list_tags

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