mcp-doculytix

MCP Server for document Q&A — extract information from documents using HachiAI's Doculytix API.

Upload a document (PDF, image, etc.) with a prompt and get structured answers back as JSON. Files larger than 1MB are automatically uploaded to the server first for efficient processing.

Quick Start

Via npx (recommended)

DOC_MCP_API_KEY=your-api-key npx @hachiai/mcp-doculytix

Via local install

npm install
npm run build
node build/index.js

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | DOC_MCP_API_KEY | Yes | — | Your HachiAI API key (JWT token from the Doculytix dashboard) | | DOC_MCP_BASE_URL | No | https://docx.hachiai.com | API base URL | | DOC_MCP_POLL_INTERVAL_MS | No | 3000 | Polling interval in ms | | DOC_MCP_MAX_POLL_ATTEMPTS | No | 120 | Max polling attempts before timeout |

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "npx",
      "args": ["-y", "@hachiai/mcp-doculytix"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP config:

{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "npx",
      "args": ["-y", "@hachiai/mcp-doculytix"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Local build

{
  "mcpServers": {
    "mcp-doculytix": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doculytix/build/index.js"],
      "env": {
        "DOC_MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Tools

document_qna

Submit a document with a prompt and get the raw response from the backend. Does not poll — returns the trace_id immediately.

Input:

• file_path (string, required) — Absolute path to the document file
• prompt (string, required) — The question or extraction prompt

Output: Raw JSON response from the backend (includes trace_id).

check_trace_status

Check the current status of a previously submitted document processing job.

Input:

• trace_id (string, required) — The trace ID from a previous submission

Output: Raw JSON response from the backend trace endpoint (includes status, request_response, value, etc.).

ask_document

Ask a natural language question about a document and get a clean, meaningful answer. Submits the document, polls until processing is complete, and extracts only the relevant answer.

Input:

• file_path (string, required) — Absolute path to the document file
• question (string, required) — A natural language question about the document

Output: JSON with success and answer fields containing the extracted result.

API Flow

1. Upload (files > 1MB) — POST /api/proxy/upload with file → returns { "file_path": "..." }
2. Submit — POST /api/proxy/qna-async with file (or file_path) + query → returns { "trace_id": "..." }
3. Poll — GET /api/proxy/trace/{trace_id} until status is fulfilled or failed

Development

npm install
npm run build
npm test
npm run test:coverage

License

MIT