MCP

DocAI exposes a remote Model Context Protocol server over Streamable HTTP.

Use MCP for agent/IDE workflows. For large PDFs or full extract options, prefer REST.

Endpoint & transport

Create a key in the workstation (Settings → API keys). See Authentication.

Never commit API keys. Use environment variables in client configs.

Tools

Tool results are a structured object: { "http_status": <int>, "body": <REST payload> }. Use body for data and errors (Errors).

extract arguments

Provide exactly one of file_base64 or file_url.

extract_batch arguments

Limits

• Decoded PDF max 10 MB each (same as REST). Larger files: use REST multipart.
• Prefer file_url over base64 when the agent would otherwise paste megabytes of base64.
• Prompts and custom fields are optional for all tiers; cloud modes use a server default prompt when omitted (see Extract).
• Auto schema keys are not a stable contract. Pin schema_id after the first Auto run.
• To retry after a timeout, pass the same idempotency_key. See Idempotency.

Client setup

Cursor

Project: .cursor/mcp.json · Global: ~/.cursor/mcp.json

{
  "mcpServers": {
    "docai": {
      "url": "https://docaiapi.subgradientlabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DOCAI_API_KEY}"
      }
    }
  }
}

1. export DOCAI_API_KEY='docai_sk_live_...'
2. Save config → refresh MCP servers in Cursor
3. Smoke-test: call balance

Claude Code

Remote Streamable HTTP is supported natively. Use your Claude Code MCP config (often project or user mcpServers) with env interpolation:

{
  "mcpServers": {
    "docai": {
      "url": "https://docaiapi.subgradientlabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCAI_API_KEY}"
      }
    }
  }
}

Syntax for env vars may be ${DOCAI_API_KEY} or product-specific. Check your Claude Code version. Then restart the session and list tools.

Claude Desktop

Claude Desktop’s claude_desktop_config.json is stdio-oriented. A bare "url" block (like Cursor) often does not work.

Option A: Custom Connector (preferred when available)
Settings → Connectors → add custom MCP → URL https://docaiapi.subgradientlabs.com/mcp → Bearer token = your DocAI API key.

Option B: mcp-remote bridge (stdio to HTTP)

{
  "mcpServers": {
    "docai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://docaiapi.subgradientlabs.com/mcp",
        "--header",
        "Authorization:${DOCAI_AUTH}"
      ],
      "env": {
        "DOCAI_AUTH": "Bearer docai_sk_live_..."
      }
    }
  }
}

Notes:

• macOS config path: ~/Library/Application Support/Claude/claude_desktop_config.json
• Requires Node.js for npx
• No space after Authorization: in the --header value (Windows/arg parsing pitfall)
• Restart Claude Desktop after edits

ChatGPT & Codex

ChatGPT desktop / Codex (CLI + IDE extension) share MCP config for Streamable HTTP.

Codex (~/.codex/config.toml or project .codex/config.toml):

[mcp_servers.docai]
url = "https://docaiapi.subgradientlabs.com/mcp"
bearer_token_env_var = "DOCAI_API_KEY"

Or static header map:

[mcp_servers.docai]
url = "https://docaiapi.subgradientlabs.com/mcp"
http_headers = { Authorization = "Bearer docai_sk_live_..." }

Prefer bearer_token_env_var so secrets stay out of the file.

ChatGPT UI: Settings → MCP / connectors (when available) → add Streamable HTTP URL + Bearer API key. If your ChatGPT build only supports OAuth connectors, use REST or Codex/Cursor instead.

VS Code + GitHub Copilot

Workspace .vscode/mcp.json or user MCP config (Copilot agent mode). Prefer "type": "http":

{
  "servers": {
    "docai": {
      "type": "http",
      "url": "https://docaiapi.subgradientlabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:docai-api-key}"
      }
    }
  }
}

Some builds use "mcpServers" instead of "servers". Match your VS Code / Copilot docs version. Enable MCP in Copilot settings if tools do not appear.

Windsurf, Cline, Continue, other IDEs

Most use a Cursor-like mcpServers JSON with a remote url + headers. Paths and env syntax differ:

If a client only supports stdio, use mcp-remote (see Claude Desktop option B).

Credits & errors

Same billing as REST. See Credits:

Call balance before large runs. Inside tool JSON: 402 = top up; 429 = backoff. Prompts are optional for all modes.

Limitations (when to use REST)

• Very large PDFs → REST multipart (MCP still caps at 10 MB per file)
• More than 10 files in one batch → REST /extract/batch
• Checkout / catalog → REST billing endpoints
• Prefer file_url over pasting multi-MB base64 into the agent context

Troubleshooting

Smoke test

After configuring a client, call balance. You should get http_status: 200 and a usage summary.

Optional raw check (expects 401 without a key; 200/JSON-RPC with a valid key depending on client Accept headers):

curl -sS -X POST 'https://docaiapi.subgradientlabs.com/mcp' \
  -H "Authorization: Bearer $DOCAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'