MCP
Model Context Protocol
Klaaro hosts an MCP server at /api/mcp so coding agents can query datasets, documents, and extracted records from your IDE. Authenticate with OAuth (recommended for Cursor, Claude Code, and GitHub Copilot) or a team API key for scripted clients.
Quick start
- Add the server in your editor. Use a one-click button below, or paste the endpoint URL into your client configuration manually. VS Code requires 1.101+ with GitHub Copilot agent mode.
- Authenticate. On first use, complete OAuth sign-in in your browser when the client prompts you. For headless or CI use, pass an API key in the
Authorizationheader instead (see Team → API keys). - Verify the connection. Ask the agent to call
list_datasetsor read a resource such asdataset://default/datasets.
Endpoint
Klaaro exposes a hosted MCP server over Streamable HTTP at the path below. The server implements MCP tools and resources backed by the same services as /api/v1.
https://klaaro.ai/api/mcpAuthentication
Two modes are supported on the same endpoint. Interactive coding agents should use OAuth: register the URL only, then sign in when prompted. The access token is a Supabase JWT scoped to your team with read, write, and export permissions.
For automation, scripts, or clients that cannot open a browser, send a team API key as Authorization: Bearer sk_…. Keys are scoped to read, write, and export; write is required for uploads and deletes, export for dataset exports.
Client setup
Cursor
Add a server in Settings → MCP with the endpoint URL only (OAuth). For API-key auth, add a headers block in ~/.cursor/mcp.json:
OAuth (URL only)
{ "url": "https://klaaro.ai/api/mcp"}API key
{ "url": "https://klaaro.ai/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" }}Claude Code
Register the remote server from your project directory. Claude Code uses Streamable HTTP transport; complete OAuth when the CLI or agent session prompts you.
claude mcp add klaaro --transport http --url https://klaaro.ai/api/mcpGitHub Copilot (VS Code)
Use Add to VS Code in Quick start, or add an MCP server entry to .vscode/mcp.json (or your user-level MCP config). Requires VS Code 1.101+ with agent mode enabled. Complete OAuth when VS Code prompts you.
{ "servers": { "klaaro": { "type": "http", "url": "https://klaaro.ai/api/mcp" } }}Other MCP clients (stdio bridge)
Clients that only support stdio can reach the hosted server via mcp-remote. Pass your API key in KLAARO_API_KEY or map it to the Authorization header your client expects:
{ "command": "npx", "args": [ "-y", "mcp-remote", "https://klaaro.ai/api/mcp" ], "env": { "KLAARO_API_KEY": "your_klaaro_api_key" }}Tools
Callable tools return JSON text content. List endpoints use cursor pagination; pass meta.nextCursor as cursor on the next call.
| Tool | Description |
|---|---|
| list_datasets | List datasets in the current team. Supports cursor pagination via cursor and limit. |
| list_documents | List documents in a dataset. Requires datasetId. Cursor-paginated. |
| get_document | Fetch a single document by documentId (metadata and pipeline status). |
| get_document_records | Fetch extracted records and classification for a document. Optional shape: clean (default), flat, or nested; includeUnapproved for HITL queue. |
| upload_document_from_url | Import a file from a public URL into a dataset and start the pipeline. Requires write scope. |
| delete_document | Delete a document by documentId. Requires write scope. |
| list_records | List extracted records for a dataset. Optional classification filter and shape (clean, flat, nested). Cursor-paginated. |
| list_classes | List extraction classes for a dataset — one class per document type, including schema definitions. |
| export_dataset | Export a dataset as sql, csv, json, or excel. Excel returns a download URL (binary). Requires export scope. |
| import_zod_schema | Convert a Zod v4 module (extractionSchema or schema export) into Klaaro SchemaField[]. Runs in the EU Daytona sandbox. |
Resources
Resources expose read-only JSON snapshots addressable by URI. They mirror the same data as the corresponding tools but fit clients that prefer MCP resource reads over tool calls.
| URI | Description |
|---|---|
| dataset://default/datasets | JSON list of datasets for the authenticated team |
| dataset://default/datasets/{datasetId}/documents | JSON list of documents in a dataset |
| dataset://default/documents/{documentId} | JSON document metadata for a single document |
| dataset://default/documents/{documentId}/records | JSON extracted records (clean shape) and classification for a document |
MCP vs REST
Use MCP when an AI agent in your editor needs structured access to datasets, documents, and exports. Use the REST API or SDKs for application code, CI pipelines, and integrations where you control HTTP directly.
- Auth: MCP accepts OAuth (browser) or API keys; REST requires API keys.
- Surface: MCP exposes a curated tool and resource set; REST covers the full v1 API including webhooks, HITL review, and observability.
- Dashboard-only: Pipeline re-run, config editing, OCR text preview, and classification suggestions are not exposed over MCP — use the app UI or REST where available.
Troubleshooting
- 401 Unauthorized: OAuth session expired or API key missing/invalid. Re-authenticate in the browser or create a new key under Team → API keys.
- 403 Forbidden: API key lacks the scope required for the tool (read, write, or export).
- Connection hangs: Confirm the URL is
https://klaaro.ai/api/mcpwith no trailing slash on the path segment. Restart the client after config changes.