MCP Beta
Use DocAI directly from your coding agent
DocAI MCP connects coding agents to DocAI document intelligence through the Model Context Protocol. Tested with Codex, Claude Code and Gemini CLI, and compatible with other MCP stdio clients.
npx -y @synairo/docai-mcp@next install
npx -y @synairo/docai-mcp@next doctor
Quick start
-
Step 1
Install
npx -y @synairo/docai-mcp@next install
The installer configures supported MCP hosts using their own normal configuration mechanism. Existing entries for other servers are never touched.
-
Step 2
Verify
npx -y @synairo/docai-mcp@next doctor
doctor checks configuration and connectivity to the DocAI API. It never prints your API key.
-
Step 3
Ask your agent
Example request to a coding agent:
Integrate DocAI document extraction into this project. Use the existing project architecture and conventions. Keep DocAI credentials server-side. Handle API and processing errors. Use structured extraction results. Add appropriate tests. Validate the integration with a sanitized sample document.
Nothing here is magic. The agent reads DocAI capabilities and integration guidance through MCP, inspects your project, and writes the integration itself. You review the diff as usual.
What the agent actually does
- Discovers DocAI MCP
- Reads capabilities
- Reads integration guidance
- Inspects the project
- Implements the integration
- Tests with sanitized input
MCP helps the coding agent understand and use DocAI. It does not move document intelligence into the coding agent.
Tools
docai_get_capabilities
Discover supported formats, limits, and API versioning before the agent writes any integration code.
docai_get_integration_guide
Retrieve maintained integration guidance the agent should follow for this project.
docai_extract_file
Submit a document from inside the current workspace and get back compact, structured extraction results. Only files inside the workspace are accessible.
docai_get_result
Retrieve the result of a job that was still processing when docai_extract_file returned.
Architecture
The MCP package does not implement a separate document-processing pipeline. It uses the same DocAI API and processing core as direct API integrations.
API for developers. MCP for coding agents.
Use MCP when
- You're working from an MCP-capable coding agent
- You want the agent to discover DocAI integration guidance
- You want agent-assisted project integration
- You want to test local workspace documents through the MCP interface
Use the REST API when
- You're building a direct production integration
- You're calling DocAI from application code
- You're implementing your own client
- You're integrating from infrastructure without MCP
Both routes use the same DocAI backend.
Security boundaries
- Workspace-restricted file access
- Local file processing is restricted to the configured workspace. Path traversal and symlink escapes outside the workspace are rejected.
- No generic shell
- DocAI MCP does not expose arbitrary shell-command execution.
- No arbitrary filesystem browser
- There is no generic filesystem exploration interface, only the workspace-restricted extraction tool.
- No arbitrary document URLs
- The MCP interface does not expose generic arbitrary URL ingestion for documents.
- Prompt-injection boundary
- Text found inside documents is treated as document data, not as instructions for the coding agent.
- Credentials
- The API key is provided through configuration and environment mechanisms. It should never be embedded in prompts or committed to source control.
- Structured output
- Structured extraction results are the default interface.
- Raw OCR
- Raw OCR is disabled by default.
Tested clients
| Client | Status | Notes |
|---|---|---|
| Codex CLI 0.147.0 | Tested | MCP stdio |
| Claude Code 2.1.231 | Tested | MCP stdio |
| Gemini CLI 0.53.0 | Tested | MCP stdio |
| Other MCP stdio clients | Protocol-compatible | Not individually certified |
Versions above are the client versions the integration was verified against. Other MCP stdio clients should work because the protocol is the same, but we do not certify them individually. DocAI is not affiliated with, endorsed by, or partnered with the vendors of these clients.
DocAI MCP Beta
What the first public beta includes:
- A local MCP stdio server, distributed on npm.
- An installer that configures supported MCP hosts, and a doctor command that checks the result.
- Verified against Codex, Claude Code and Gemini CLI.
- Workspace-restricted local file access.
- Compact structured extraction results.
- Idempotent job submission, so a retry does not process a document twice.
- The security boundaries described above.
Beta means the tool surface may still change between versions. Pin a version in long-lived configuration.
Package
| Package | @synairo/docai-mcp |
|---|---|
| Publisher | Synairo, the npm organization operated by SYNAIRO sp. z o.o., which publishes DocAI. |
| Current beta | 0.1.0-beta.1 |
| Onboarding channel | next |
| Requires | Node.js 18.17 or newer |
| npm | https://www.npmjs.com/package/@synairo/docai-mcp |
Long-lived host configuration generated by the installer pins the exact version, for example npx -y @synairo/docai-mcp@0.1.0-beta.1 serve, never the next channel tag.
Documents processed through MCP draw on the same page balance as the REST API, because they run through the same DocAI backend.