MCP server
The DocAI MCP server gives a coding agent direct access to your knowledge
bases. It runs locally over stdio, calls the same public /v1 API documented
in the API reference, and needs one environment variable.
This page is the tool reference. To install the server in Claude Code, Cursor or Codex, see plugins and commands. For the instructions that ship alongside it, and why they are the safety mechanism, see agent guidance.
Each group of tools below points at the guide for the endpoints it wraps.
Configuration
| Variable | Required | Default | Effect |
|---|---|---|---|
DOCAI_API_KEY | yes | — | Sent as x-api-key on every request |
DOCAI_BASE_URL | no | https://api.providus.ai | Point at an on-prem deployment; trailing slashes are stripped |
DOCAI_MCP_ALLOW_DESTRUCTIVE | no | unset | true, 1 or yes registers the two permanent-delete tools |
A missing key fails at startup rather than on the agent's first tool call:
Code
That is deliberate. One clear line on stderr beats a 401 on every tool the model tries. On a healthy start the server writes a single diagnostic line, also to stderr, because stdout is the protocol transport and anything else written there corrupts the stream:
Code
Twenty, not 22, when DOCAI_MCP_ALLOW_DESTRUCTIVE is unset. That count is
the quickest way to tell which configuration actually loaded.
The tools
Twenty-two tools. Ten are annotated read-only and cannot change anything.
Knowledge bases
These wrap the endpoints in knowledge bases and search.
| Tool | Parameters | What it does |
|---|---|---|
docai_list_knowledge_bases | none | Every knowledge base the key can see. Read-only. |
docai_create_knowledge_base | name, description (optional) | Creates one. Names must be unique within the organization. |
docai_kb_index | kb_id | Every file in a knowledge base with parse status and artifact links, in one call. Read-only. |
Getting files in
| Tool | Parameters | What it does |
|---|---|---|
docai_list_files | kb_id (optional) | Lists files, optionally scoped to one knowledge base. Read-only. |
docai_upload_file | path, kb_id, folder_id (optional) | Uploads one local file. path must be absolute. Uploading does not parse. |
Processing
The parse tools wrap parsing, the extract tools wrap
extraction, and docai_classify and docai_split wrap
document workflows. All of them spend
credits.
| Tool | Parameters | What it does |
|---|---|---|
docai_parse_file | file_id | Queues a parse. Returns a job to poll. Costs credits per page. |
docai_parse_bulk | file_ids (at least one) | Queues parses for many files. Costs credits for every page of every file. |
docai_extract | file_id, schema (object) | Extraction on a parsed file with an inline JSON Schema, kept as a durable artifact. This endpoint does not accept schema_id — use docai_extract_run. |
docai_extract_run | file_id, schema_id (optional), schema (optional object), segment_ids (optional) | Runs a saved schema by id, or DocAI's own {title, fields} shape — not JSON Schema. Queues an operation; the result arrives inline when you poll it. |
docai_extract_bulk | file_ids (at least one), schema_id (optional) | Queues extraction across many files. |
docai_classify | file_id, classes (array of strings, at least one) | Classifies a document and its pages, returning the classes and per-page assignments. Without classes every page comes back Unknown and the run still costs a credit, so the API rejects it. |
docai_suggest_classes | file_id, guidelines (optional) | Asks DocAI to propose a class list from the document, instead of inventing class names. Queued; costs 1 credit. |
docai_split | file_id, suggest_rules (optional), rules (optional array of objects) | Splits a PDF holding several documents. With suggest_rules it proposes rules instead of running. |
docai_split_download | file_id, start_page, end_page, title, out_dir (optional) | Saves one split record as its own PDF and returns the path. The API sends PDF bytes, not JSON. Free. |
docai_split is the one tool that changes endpoint based on a flag:
suggest_rules sends POST /v1/split/rules/suggest, otherwise
POST /v1/split/runs. Both are queued work — poll with
docai_operation_status, not docai_job_status.
Schemas
Schemas are covered in extraction.
| Tool | Parameters | What it does |
|---|---|---|
docai_generate_schema | file_id, title (optional) | Derives a reusable extraction schema from a parsed document. |
docai_list_schemas | none | Saved schemas, so one can be reused by id. Read-only. |
Status
| Tool | Parameters | What it does |
|---|---|---|
docai_job_status | file_id, job_id, include_events (optional) | Parse or extract job status. include_events returns the stage-by-stage log. Read-only. |
docai_operation_status | operation_id | Queued workflow status, such as a split run. output stays null until status is completed. Read-only. |
A job needs both ids. docai_job_status reads
/v1/files/{file_id}/jobs/{job_id}, so a job id alone will not do — carry the
file id with it.
Set include_events when a job has failed. Without it you get the terminal
status and nothing about which stage produced it.
Reading out
Artifacts and segments are described in parsing.
| Tool | Parameters | What it does |
|---|---|---|
docai_read_artifact | file_id, key | One artifact from the file's newest parse. Read-only. |
docai_get_segments | file_id | Segments with page coordinates, for citing an exact place in the source. Read-only. |
key is an enum, and only these seven values are accepted:
Code
result_md is the parsed markdown, result_json the extraction output,
grounding_json the page coordinates. The tool resolves the manifest itself:
it lists the file's artifacts, sorts by created_at and reads from the newest
one, so you never pass a manifest id. If the file has never been parsed it
fails with No parse artifacts for file <id>. Parse it first.
Search
The search parameters and the response shape are in knowledge bases and search.
| Tool | Parameters | What it does |
|---|---|---|
docai_search | kb_id, query, limit (optional, 1–100), file_ids (optional), table_only (optional) | Full-text search over parsed evidence. Read-only. |
It calls no model, so it spends no credits, and it returns exact file and
segment pointers to cite. file_ids narrows the search to specific documents;
table_only restricts hits to table content.
Account
| Tool | Parameters | What it does |
|---|---|---|
docai_credits | none | Remaining credits and the monthly quota. Read-only. |
Deleting
| Tool | Parameters | What it does |
|---|---|---|
docai_delete_file | file_id | Soft delete. The row is kept, the file leaves lists and indexes, and it can be restored. |
docai_permanent_delete_file | file_id | Removes the file, every version, and all parsed artifacts. Gated. Cannot be undone. |
docai_delete_knowledge_base | kb_id | Removes the knowledge base and everything in it. Gated. Cannot be undone. |
A worked session
Index a folder of contracts, then answer a question with citations. Nine calls, and only one of them spends money.
1. Find the knowledge base. docai_list_knowledge_bases returns names and
ids. If none fits, docai_create_knowledge_base with name: "Contracts".
2. Check the balance first. docai_credits before anything bulk. The
agent should report the balance to you and wait, rather than discovering
halfway through a folder that the quota is gone.
3. Upload the files. docai_upload_file once per document — absolute
path plus kb_id. Uploading does not parse; that is the next step. (Bulk
folder import and sync are DocAI web-app features, not agent tools.)
4. See what state everything is in. docai_kb_index with kb_id. One
call returns every file, its parse status and its artifact links — which is
also how you collect the file ids for the next step.
5. Parse what is unparsed. docai_parse_bulk with the file ids from the
index. This is the call that costs credits, per page, per file.
6. Wait. Poll docai_kb_index to watch parse status move across the whole
batch in one request. Drop to docai_job_status with include_events: true
only for a file that failed, where you need the stage that broke.
7. Search rather than read. docai_search with kb_id and a query such
as "termination for convenience". It costs nothing and comes back with file
and segment pointers.
8. Read only the hits. docai_read_artifact with key: "result_md" for
the one or two files search pointed at. Reading all 34 documents to find one
clause would burn context for no gain, and gives a worse answer than the
pointers already did.
9. Cite precisely. docai_get_segments for the answering file gives page
coordinates, so the answer points at the line it came from rather than at the
document.
To pull the same field out of every contract instead, replace steps 7–9 with
docai_generate_schema on one representative file, then docai_extract_bulk
with the resulting schema_id across the set. Check docai_credits first —
that one spends per file.
Destructive tools
docai_permanent_delete_file and docai_delete_knowledge_base are not
registered unless DOCAI_MCP_ALLOW_DESTRUCTIVE is set to true, 1 or
yes. They are skipped at registration rather than registered and refusing.
An agent cannot call a tool it cannot see, and it cannot argue its way past one
that does not exist.
docai_delete_file is always available. It is a soft delete: the row stays,
the file leaves lists and indexes, and it can be restored.
The flag has to be present in the environment the editor launches the server in, and the server restarted afterwards. Setting it in a shell that the editor did not inherit changes nothing.
Security
A DocAI API key is organization-root and bypasses RBAC. It is not scoped to a knowledge base, and there is no read-only key today. Anything holding your key can read and write every knowledge base in your organization, whatever roles and grants you have configured for people.
Consequences worth being explicit about:
- An editor config file containing a key is production access to the whole organization. Treat it like a deploy credential, and keep it out of version control.
- Any agent you connect can reach every knowledge base, not only the one you had in mind for the session.
- Revoking the key is the only containment. There is no per-knowledge-base downgrade to fall back on.
Scoped keys and a browser login flow are planned.
The key itself is never written into a log or an error message. Failures carry
the HTTP status, the method and path, the API's stable code, and the message
— see error codes. Error text reaches the model and may end up in a
transcript, so nothing else is put in it.