Developers

MCP

MCP

Connect AI agents and MCP clients to Kuration over streamable HTTP. The server exposes tools for projects, columns, enrichment tools, filters, ICPs, and credits—the same workspace data you see in the app.

Every tool returns a JSON string with a stable success/error envelope so agents can parse results reliably.

Endpoint

https://mcp.kurationai.com/mcp/

This is the streamable HTTP MCP path. A status page and OAuth metadata are available at the host root (see Health and status routes).

Authentication

OAuth (Claude and MCP-native clients)

Kuration MCP is an OAuth 2 resource server. MCP clients discover auth through:

https://mcp.kurationai.com/.well-known/oauth-protected-resource

Send a valid OAuth access token as Authorization: Bearer <token>. For Claude, use a custom connector and sign in through the browser—see Connect with Claude.

Send the same kur-api-key you use for the Workflow API. Create or rotate it in Settings → Integrations → API (/settings/integration?tab=api).

The server accepts the key in the kur-api-key header. Internally it is bridged to bearer auth so MCP transport verification works without weakening OAuth flows.

Client configuration

Add the server to your MCP client's mcpServers configuration:

{
  "mcpServers": {
    "kuration-ai": {
      "type": "http",
      "url": "https://mcp.kurationai.com/mcp/",
      "headers": {
        "kur-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your key from the app. Do not commit real keys to version control. Exact file location and wrapper shape depend on your MCP client—use its docs if the JSON lives inside another config object.

Tools can change live data

Many MCP tools create projects, run builders, add columns, and execute enrichment tools. These operations consume credits and quota. Prefer test workspaces while experimenting.

Response format

All tools return a JSON string (not a raw object) with one of these shapes.

Success

{
  "ok": true,
  "data": {}
}

The data payload matches the underlying Kuration API where applicable (project, rows, tool result, etc.).

Error

{
  "ok": false,
  "error": true,
  "code": "error_code",
  "detail": {},
  "status_code": 400
}
code Typical cause
unauthorized Missing or invalid API key / bearer token
forbidden Authenticated but not allowed (e.g. API access locked)
not_found Project, row, or resource not found or access denied
validation_error Invalid parameters or JSON payload
parse_error Malformed JSON in *_json string arguments
http_error Upstream HTTP failure
internal_error Unexpected server error

Agent hints

Tools carry MCP ToolAnnotations to help agents plan safe call sequences. These are hints only—not a security boundary.

Hint Meaning
Read-only Does not mutate workspace data (e.g. list_projects, get_project_rows)
Write Creates or updates data (e.g. run_builder, create_column)
Destructive Soft-deletes or irreversible actions (e.g. delete_project, delete_rows)

Prefer read-only discovery tools (list_builders, list_tools, search_tools) before write tools.

Typical flow

A common automation path for a new list:

  1. list_builders — discover allowed initial-list builders and form field templates.
  2. run_builder — create a project with builder_id and form_data_json.
  3. get_project / get_project_rows — poll until the builder finishes and rows are available.
  4. create_column + run_pending_columns — add enrichment columns and run them.
  5. get_project_rows — read enriched results.
flowchart TD
  listBuilders[list_builders]
  runBuilder[run_builder]
  getProject[get_project / get_project_rows]
  createCol[create_column]
  runCols[run_pending_columns]
  results[get_project_rows]

  listBuilders --> runBuilder
  runBuilder --> getProject
  getProject --> createCol
  createCol --> runCols
  runCols --> results

Health and status routes

These HTTP routes on https://mcp.kurationai.com do not require authentication:

Route Description
GET / HTML status page (MCP URL, OAuth metadata link, tool count)
GET /health JSON liveness
GET /healthz JSON liveness (alias)
GET /favicon.ico Favicon asset
GET /favicon.png Favicon asset

Next steps