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 in the docs, 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/mcpListed in the Official MCP Registry as ai.klaaro/klaaro.
Authentication
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 the Klaaro datasets accessible to the authenticated team. Returns dataset IDs, slugs, names, descriptions, document counts, and timestamps in a cursor-paginated data/meta response; pass meta.nextCursor as cursor to continue. |
| list_documents | List documents in one Klaaro dataset, including each document’s ID, filename, file type, processing status and current step, classification, and timestamps. Requires datasetId and returns a cursor-paginated data/meta response for discovering IDs to use with document tools. |
| get_document | Get one Klaaro document by documentId. Returns its dataset, filename, type, size, processing status and current pipeline step, assigned class, error details, and timestamps; use this to inspect metadata or poll processing state, not to fetch extracted records. |
| get_document_records | Get the extracted records and assigned class for one Klaaro document. Requires documentId; defaults to clean values, supports flat field metadata or nested FieldView metadata via shape, and excludes unapproved records unless includeUnapproved is true. |
| upload_document_from_url | Import a document into a Klaaro dataset from a publicly reachable URL and start Klaaro’s OCR, classification, and extraction pipeline. Requires url and datasetId; returns the created document metadata so its processing status can be checked with get_document. |
| delete_document | Delete one Klaaro document by documentId, removing it from normal document listings. This mutating operation targets the authenticated team’s data; use get_document first when the document is uncertain. |
| list_records | List extracted records across a Klaaro dataset. Requires datasetId; optionally filters by classification, supports clean values, flat field metadata, or nested FieldView metadata via shape, and returns cursor-paginated data/meta results. |
| list_classes | List the document classes configured for a Klaaro dataset. Requires datasetId; returns each class’s ID, slug, name, description, color, extraction schema, schema and class hashes, and timestamps, with one class representing a document type. |
| export_dataset | Export records from a Klaaro dataset as SQL, CSV, JSON, or Excel, optionally filtered by classification. Requires datasetId and format; text formats are returned directly, while Excel returns a download URL for the binary workbook. |
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.