Reference

MCP Server

The Model Context Protocol (MCP) is an open standard that lets AI applications call external tools. The HyperAPI MCP server gives any MCP client — Claude Desktop, Cursor, VS Code, Claude Code and others — tools to parse, extract, classify, split and redact documents with HyperAPI.

How it works

Your AI app

Claude, Cursor, VS Code, …

HyperAPI MCP server

runs on your machine

HyperAPI API

/v1/* with your API key

The server is a thin adapter over the public /v1/* API, built on the Python SDK. It authenticates with your own hk_live_ or hk_test_ key, so usage is billed exactly like direct API calls. Long operations run as async jobs; the tools submit and wait for the result automatically.

Installation

Python 3.10+

stdio

Streamable HTTP

The SDK and the MCP server will be published to PyPI soon. In the meantime, clone both repositories side by side and install them from GitHub.

git clone https://github.com/hyprbots/hyperapi-sdk
git clone https://github.com/hyprbots/hyperapi-mcp

pip install -e ./hyperapi-sdk    # 1. the Python SDK the server is built on
pip install -e ./hyperapi-mcp    # 2. the MCP server

git clone https://github.com/hyprbots/hyperapi-sdk
git clone https://github.com/hyprbots/hyperapi-mcp

pip install -e ./hyperapi-sdk    # 1. the Python SDK the server is built on
pip install -e ./hyperapi-mcp    # 2. the MCP server

To check the install, run the server directly. It speaks the stdio transport by default, which is what desktop MCP clients use — they start it for you, so you don't need to keep it running yourself.

export HYPERAPI_API_KEY=hk_live_your_key_here
python /path/to/hyperapi-mcp/main.py    # stdio transport (default)

export HYPERAPI_API_KEY=hk_live_your_key_here
python /path/to/hyperapi-mcp/main.py    # stdio transport (default)

Connect your AI app

Register the server with your client. Use the absolute path to main.py in your clone. Configuration files: claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json (Cursor) and .vscode/mcp.json (VS Code). Claude Code registers it from the command line.

{
  "mcpServers": {
    "hyperapi": {
      "command": "python",
      "args": ["/absolute/path/to/hyperapi-mcp/main.py"],
      "env": { "HYPERAPI_API_KEY": "hk_live_your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "hyperapi": {
      "command": "python",
      "args": ["/absolute/path/to/hyperapi-mcp/main.py"],
      "env": { "HYPERAPI_API_KEY": "hk_live_your_key_here" }
    }
  }
}

Keep your API key out of the conversation

Set HYPERAPI_API_KEY in the server's env block as shown. Every tool also accepts an optional api_key argument, but tool arguments enter the model's context — prefer the environment variable. See Authentication.

Tools

The server exposes 11 tools. Each one has a typed input and output schema, so your client knows what arguments to send and what comes back.

Tool	What it does	API reference
`parse_document`	OCR a document and return its text. mode="advanced" returns layout-aware structure; include_boxes adds line and word boxes with typography; include_image adds a page-image URL.	Parse
`extract_document`	Extract structured fields (entities and line items). category: financial (default) or non_financial; parse_mode: fast or advanced.	Extract
`extract_advanced`	Extraction with automatic document-type detection. No category needed.	Extract
`classify_document`	Categorize a document's type. options tunes depth, classes, and budgets.	Classify
`split_document`	Segment a multi-document file into labelled parts with page ranges.	Split
`redact_document`	Remove (redact) or replace (deidentify) PII. pii_config selects PII types; include_logos masks logos.	Redact
`process_document`	Parse and extract on a single upload; returns { ocr, data }.	—
`upload_document`	Upload once and get a reusable document_key.	Upload
`get_job`	Fetch a job's status and, when finished, its result.	Retrieving results
`list_recent_jobs`	List your account's recent jobs, newest first. limit is 1–100.	Retrieving results
`cancel_job`	Cancel a job. Idempotent — cancelling a finished job succeeds.	—

Passing documents

Document tools take a file object with the file name (its extension determines the file type) and the base64-encoded bytes. A data: URL is also accepted as content, and an optional content_type overrides the type inferred from the extension.

{
  "file": {
    "filename": "invoice.pdf",
    "content": "<base64-encoded file bytes>"
  }
}

{
  "file": {
    "filename": "invoice.pdf",
    "content": "<base64-encoded file bytes>"
  }
}

Results come back both as JSON text and as MCP structured content, so clients that understand output schemas get typed data while text-only clients still work.

Best for small files

In desktop apps the model itself has to produce the base64 content for each tool call, which is slow and costly for large files. The server works best with small documents, or in clients that attach files to tool calls directly. For large or high-volume workloads, call the REST API or Python SDK directly.

Running as a remote server

For a shared deployment, run the server with the Streamable HTTP transport. The MCP endpoint is /mcp and a health check is served at /_health.

export HYPERAPI_API_KEY=hk_live_your_key_here
export HYPERAPI_MCP_ALLOWED_HOSTS=mcp.example.com

python main.py --transport streamable-http --host 0.0.0.0 --port 8891
# MCP endpoint:  http://<host>:8891/mcp
# Health check:  http://<host>:8891/_health

export HYPERAPI_API_KEY=hk_live_your_key_here
export HYPERAPI_MCP_ALLOWED_HOSTS=mcp.example.com

python main.py --transport streamable-http --host 0.0.0.0 --port 8891
# MCP endpoint:  http://<host>:8891/mcp
# Health check:  http://<host>:8891/_health

Expose it deliberately

The HTTP transport binds to loopback (127.0.0.1) by default. When you serve it on a public hostname, put it behind a reverse proxy that terminates TLS and set HYPERAPI_MCP_ALLOWED_HOSTS (and, for browser clients, HYPERAPI_MCP_ALLOWED_ORIGINS) so the built-in DNS-rebinding protection accepts forwarded requests. If one API key serves many users, set HYPERAPI_MCP_DISABLED_TOOLS=list_recent_jobs,get_job,cancel_job — those tools act on the whole account, so any user could read or cancel other users' jobs.

Configuration

The server is configured with environment variables.

Variable	Default	Description
`HYPERAPI_API_KEY`	`—`	API key used when a tool call omits api_key.
`HYPERAPI_BASE_URL`	`https://apis.hyperbots.com`	Platform base URL.
`HYPERAPI_TIMEOUT_SECONDS`	`120`	Default request timeout.
`HYPERAPI_EXTRACT_TIMEOUT_SECONDS`	`600`	Timeout for extract, redact and process.
`HYPERAPI_POLL_INTERVAL_SECONDS`	`3`	Async job poll interval.
`HYPERAPI_POLL_TIMEOUT_SECONDS`	`3600`	Async job poll timeout.
`HYPERAPI_MCP_HOST`	`127.0.0.1`	Bind host (HTTP transport).
`HYPERAPI_MCP_PORT`	`8891`	Bind port (HTTP transport).
`HYPERAPI_MCP_DNS_REBINDING_PROTECTION`	`true`	Origin / DNS-rebinding protection (HTTP transport).
`HYPERAPI_MCP_ALLOWED_HOSTS`	`loopback`	Comma-separated Host allow-list. Set it when serving behind a public hostname.
`HYPERAPI_MCP_ALLOWED_ORIGINS`	`—`	Comma-separated browser Origin allow-list.
`HYPERAPI_MCP_DISABLED_TOOLS`	`—`	Comma-separated tool names to hide from the client. Unknown names fail startup.

Troubleshooting

401 — invalid API key

Check that HYPERAPI_API_KEY is set in the server's env block and that the key is active in your dashboard. See Errors.

The tools don't appear

Fully restart your AI app after editing its configuration, and use absolute paths to main.py — clients don't start servers from your project directory.

python not found, or the module fails to import

Desktop apps don't inherit your shell's PATH. Set command to the full path of the interpreter you installed into (for example /path/to/venv/bin/python).

Long documents time out

Raise HYPERAPI_EXTRACT_TIMEOUT_SECONDS or HYPERAPI_POLL_TIMEOUT_SECONDS. If the tool call still gives up, the job keeps running on the platform — find it with list_recent_jobs and fetch the result with get_job. See also Async mode.