Pipeline as an MCP server
A pipeline can be exposed as an MCP server (Model Context Protocol). An external AI assistant (Claude Code, VS Code with GitHub Copilot, Cursor, Claude Desktop…) can then call it as a tool during a conversation, without going through the web interface or writing code.
Each exposed pipeline has its own address:
https://<your-organization>.hocnota.com/api/mcp/pipelines/<pipeline-id>
What the assistant can do
The tools on offer depend on the pipeline's form.
Chat pipeline — one ask tool: the assistant sends a message and gets the pipeline's reply. The reply carries a conversation ID. If the assistant passes it back on the next call, the conversation continues and the pipeline sees the history.
Document pipeline — four tools, because an analysis can take several minutes, often longer than an assistant will wait for a single call:
| Tool | Purpose |
|---|---|
submit_document | submits a document (.docx, .pdf, .pptx, .xlsx) and returns a job ID |
get_job_status | gives the job's status and progress; can wait up to 45 s for the analysis to finish |
get_job_result | returns the annotations produced and a temporary download link to the annotated document |
cancel_job | cancels an ongoing analysis |
The document can be sent in either of two ways:
- as base64, with its file name. This suits assistants that can read your files (Claude Code, for example);
- as a public URL that hocnota downloads itself. Shared Google Docs and Google Slides links are converted automatically. Private or local network addresses are refused.
Annotations are included in the result only if the pipeline has "Output the annotation list as JSON" ticked. The download link is always provided; it stays valid as long as your organization's download links do.
For an extraction portfolio (JSON output), the four tools are the same. submit_document also accepts images, and get_job_result returns the extracted JSON (extraction), its conformity verdict (valid) and the format deviations (errors), with no download link.
Support documents cannot be sent over MCP yet.
Setting it up
- Expose the pipeline. In the pipeline editor, open ⚙ Pipeline settings and tick Expose as an MCP server. The pipeline must also be active.
- Describe the tool. The Tool description field is read by the assistant to decide when to call your pipeline: say what it does and what it returns. Left empty, the pipeline description is used instead.
- Prepare an API key. In Manager → Settings → API Keys, create or edit a key: tick the MCP server domain and assign the pipeline to it (see Accessing a Pipeline via API).
- Configure the assistant. In the editor, the API code panel has an MCP tab: pick the key, then copy the configuration for your client (Claude Code, VS Code, Cursor, Claude Desktop). The tab warns you if the pipeline is not exposed yet or if the key lacks the MCP server domain.
For Claude Code, for example:
claude mcp add --transport http hocnota-review \
https://acme.hocnota.com/api/mcp/pipelines/<pipeline-id> \
--header "Authorization: Bearer hnk_..."
Who can call the pipeline
All three conditions must hold, otherwise the server refuses the call:
- the API key carries the MCP server domain. This domain is never ticked by default, existing keys included;
- the key is assigned to this pipeline;
- the pipeline is active and exposed over MCP.
Unticking "Expose as an MCP server" cuts access immediately, for every key. Your organization's IP firewall also applies to these calls.
Each key sees only its own jobs and conversations. A key assigned to several pipelines cannot read, from one pipeline's server, the jobs started on another.
Cost and quotas
An analysis started over MCP is a job like any other: it shows up in statistics (MCP channel) and costs, and counts toward the organization's quotas. On the hosted service, each call to the ask and submit_document tools uses one call credit; with an exhausted balance, the tool returns an error starting with [credits_exhausted] (see Call credits). Status, result and cancellation are free. An assistant can chain calls on its own: keep the MCP server domain for keys whose use you control.