MCP Server

KaiwaDB exposes its query generation and execution capabilities over the Model Context Protocol . Any MCP-capable agent (Claude Code, Cursor, custom SDK agents) can list your schemas, generate pipelines from natural language, and run them against your databases through your tunnels.

Endpoint: https://api.kaiwadb.com/mcp (Streamable HTTP)

Authentication

Two ways in, one credential underneath:

Bearer token for clients that send headers (Claude Code, Cursor, IDEs, SDK agents): create a token in the app and paste it into the client config.
OAuth for claude.ai and ChatGPT connectors: paste only the server URL. The connector discovers the KaiwaDB authorization server, sends you to a consent page where you sign in, pick the organization and an access cap, and the connection is authorized. No token to copy.

Both paths mint the same access token (prefix kwdb_). An access token:

is bound to one organization,
acts as the user who created it, so grants and memberships apply,
carries an access cap that can only narrow, never widen, what that user may do.

Cap	Ceiling on what the agent can do
`viewer`	At most read schemas, search pipelines, run existing queries
`editor`	At most the above, plus generate new pipelines (spends operations)
`admin`	No extra cap: everything the creating user’s own role already allows

The cap never grants access. A viewer member with an admin token is still a viewer. The reachable schemas and databases are always the ones the creating user can reach.

Create a token in the app under Settings → MCP Tokens. The raw token is shown once; store it in your agent’s secret storage. OAuth connections show up on the same page under the client’s name. Revoke either kind there; revoking an OAuth connection also invalidates its refresh token. Removing a user from the organization revokes all their tokens implicitly.

Do not use API keys or session credentials on the MCP endpoint. It rejects them. Access tokens are the only accepted credential.

Setup

Claude Code


claude mcp add kaiwadb https://api.kaiwadb.com/mcp \
  --transport http \
  --header "Authorization: Bearer kwdb_..."

claude.ai / ChatGPT

Add a custom connector with the URL https://api.kaiwadb.com/mcp and pick OAuth. The browser opens the KaiwaDB consent page: sign in, choose the organization and the access cap, approve. ChatGPT requires developer mode (Settings → Apps & Connectors) to add custom connectors.

.mcp.json


{
  "mcpServers": {
    "kaiwadb": {
      "type": "http",
      "url": "https://api.kaiwadb.com/mcp",
      "headers": {
        "Authorization": "Bearer kwdb_..."
      }
    }
  }
}

Other clients

Any client that speaks MCP Streamable HTTP works. Send the token as a standard bearer header:


POST https://api.kaiwadb.com/mcp
Authorization: Bearer kwdb_...
Content-Type: application/json
Accept: application/json, text/event-stream

Tools

Tool	Cost	Purpose
`list_schemas`	free	Schemas the token can reach
`list_databases`	free	Databases the token can query
`list_tunnels`	free	Tunnels and their online state
`show_schema`	free	Full schema source (tables, fields, types)
`search_pipelines`	free	Find existing approved pipelines by semantic similarity
`compile_pipeline`	free	Pipeline → D2 diagram source, or the exact engine query
`generate_pipeline`	spends operations	Natural language → kaiwa pipeline (cached when identical)
`run_query`	free	Execute a pipeline against a database (rows capped at 50)
`show_query`	free	Kaiwa source of a pipeline
`show_lang_spec`	free	The kaiwa language specification

A typical agent flow:

list_schemas → pick a schema.
search_pipelines: an existing approved pipeline is free and instant.
generate_pipeline when nothing matches (slow; spends operations).
run_query with the returned pipeline_id.

Limits

Requests are rate limited per token (burst 30, sustained 30/minute). Clients should honor the Retry-After header on 429.
Generation is billed to the organization exactly as in the app, and is attributed to the user who created the token.
Query results are capped at 50 rows per call; the response reports total_rows and truncated.