Arkrel
Sign in

MCP server

Let Claude, Cursor, ChatGPT, or any MCP-speaking agent call Arkrel directly to turn a document into verified data.

During maintenance, mutating tools return HTTP 503 with JSON-RPC error code -32004 and Retry-After: 60. Retry after that delay. Read tools remain available under the release guard. During the cutover bridge, all requests return HTTP 503 with a plain JSON MAINTENANCE error and Retry-After: 60.

What it is

Organization rate limits are shared with the app and REST API: 30 bookkeeping mutations, 60 document extractions, and 300 general reads per minute. A 429 response includes Retry-After.

A remote MCP (Model Context Protocol) server at https://arkrel.com/mcp, so an AI agent can extract and verify a document without you writing any integration code. It's a thin wrapper over the same REST API described in the rest of these docs: every tool call runs through the identical ingest, quota, and verification pipeline as POST /v1/documents.

  • Transport: Streamable HTTP, stateless (no session to manage), one POST endpoint, JSON responses.
  • Auth: the same Authorization: Bearer <API key> as the REST API. See Authentication.
  • No account or extra setup on our side: any API key that works against /v1 works against /mcp.

Endpoint

text
POST https://arkrel.com/mcp

A missing or invalid key gets a 401 with a WWW-Authenticate header and a JSON-RPC error body pointing at where to create one. GET and DELETE aren't used by this stateless transport and return 405.

API keys and MCP credentials are checked against their creating user on every request. If that user has a password without enabled TOTP, requests return HTTP 403 TWO_FACTOR_SETUP_REQUIRED. Organization/service keys with no creating user keep their existing behavior. MCP returns JSON-RPC error -32005 with error.data.code TWO_FACTOR_SETUP_REQUIRED before processing the request. Enable an authenticator app in the dashboard and retry.

Tools

extract_document

Upload a document (by URL or base64) and get back verified fields, tables and checks, usually in one call.

Inputs

  • file_url or file_base64 + filename (exactly one)
  • document_type (optional; the API does not classify documents. Omitting this defaults to "invoice")
  • schema_id (for a custom schema), metadata (object)
  • wait_seconds 0-50, default 25: how long to wait for a terminal status before returning early

Output

Status, reasons, and (once terminal) the same fields/tables/checks shape as GET /v1/documents/{id}/result. Still processing after wait_seconds? You get the queued document_id back. Call get_document_result with it.

get_document_result

Poll a document you already submitted.

Inputs

  • document_id (required)
  • wait_seconds 0-50, default 20

Output

Same shape as extract_document's. Only ever returns documents belonging to your own organization.

list_documents

Browse your organization's recent documents.

Inputs

  • status (optional filter), limit 1-50, default 10

Output

A list of id, filename, document_type, status, created_at, completed_at.

get_usage

Check plan and quota before (or after) a big batch.

Inputs

None.

Output

plan, pages_included, pages_used, pages_pending, pages_overage, and the current period's period_start/period_end.

A result larger than about 200KB has its tables trimmed to the first rows inline, with a note and the REST result_urls (JSON, CSV, XLSX) to fetch the rest.

Claude Code

bash
claude mcp add --transport http arkrel https://arkrel.com/mcp \
  --header "Authorization: Bearer $ARKREL_API_KEY"

Claude Desktop

Claude Desktop's built-in remote-connector flow (in Settings, under Connectors) is built around OAuth and has no documented way to attach a static API key header yet. Until that lands, bridge it with the community mcp-remote proxy in your local config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

json
{
  "mcpServers": {
    "arkrel": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://arkrel.com/mcp",
        "--header",
        "Authorization:${ARKREL_AUTH_HEADER}"
      ],
      "env": { "ARKREL_AUTH_HEADER": "Bearer sk_live_..." }
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or Cursor's global MCP settings:

json
{
  "mcpServers": {
    "arkrel": {
      "url": "https://arkrel.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json. VS Code prompts for the key once and stores it securely instead of writing it into the file:

json
{
  "inputs": [
    { "type": "promptString", "id": "arkrel-api-key", "description": "Arkrel API key", "password": true }
  ],
  "servers": {
    "arkrel": {
      "type": "http",
      "url": "https://arkrel.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:arkrel-api-key}"
      }
    }
  }
}

OpenAI Responses API

Pass Arkrel as a remote MCP tool directly in the request body:

json
{
  "model": "gpt-4.1",
  "input": "Extract this invoice and tell me if anything doesn't add up: https://example.com/invoice.pdf",
  "tools": [
    {
      "type": "mcp",
      "server_label": "arkrel",
      "server_url": "https://arkrel.com/mcp",
      "authorization": "$ARKREL_API_KEY",
      "require_approval": "never"
    }
  ]
}

n8n

Add an MCP Client Tool node and set:

text
Endpoint: https://arkrel.com/mcp
Server Transport (if shown): HTTP Streamable
Authentication: Bearer
Bearer Token: <your Arkrel API key>

All setups, side by side

claude mcp add --transport http arkrel https://arkrel.com/mcp \
  --header "Authorization: Bearer $ARKREL_API_KEY"