Unstract MCP Server

A public remote Model Context Protocol server that exposes an Unstract API Deployment to AI agents.

It runs on Vercel as a stateless Streamable HTTP endpoint and is compatible with OpenAI and Claude (and any other MCP client that speaks Streamable HTTP).

How it works

The Unstract platform already ships a native MCP server (backend/mcp_server/). This project is a thin, stateless proxy in front of it:

Claude / OpenAI  ──Bearer <MCP_PUBLIC_KEY>──▶  this server (Vercel)
                                                     │
                                                     │ Authorization: Bearer <UNSTRACT_API_KEY>
                                                     ▼
                                    Unstract MCP endpoint
                          /deployment/api/<org>/<api_name>/mcp

The Unstract API key lives only in the server's environment variables. Clients never see it — they authenticate with a separate public key you issue. The proxy forwards JSON-RPC envelopes verbatim and returns the upstream response untouched, so none of Unstract's business rules are reimplemented here:

• S3 pre-signed URL validation

• quota / rate-limit accounting

• input schemas and their validation errors

• the one-shot semantics of a completed extraction result

Related MCP server: AgentHansa HTTP MCP

Tools

extractDocument arguments

getExecutionStatus arguments

⚠️ Critical behaviour to respect

1. extractDocument always returns an execution_id. Never re-run it after receiving one — every retry consumes quota a second time. Poll with getExecutionStatus instead.

2. A completed result can only be read once. The first COMPLETED poll consumes it; a second poll returns "This result was already acknowledged and is no longer retrievable."

3. Documents must already be on S3 and referenced by an HTTPS URL whose host ends in amazonaws.com. Any other host is rejected. For private objects, generate a pre-signed URL.

4. timeout: -1 runs asynchronously — use it when you intend to poll.

Configuration

Set these environment variables in your Vercel project:

Client configuration

Claude Desktop / Claude Code

claude mcp add --transport http unstract \
  https://<your-deployment>.vercel.app/mcp \
  --header "Authorization: Bearer <MCP_PUBLIC_KEY>"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "unstract": {
      "type": "http",
      "url": "https://<your-deployment>.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_PUBLIC_KEY>"
      }
    }
  }
}

OpenAI

OpenAI's MCP connector expects an HTTP endpoint with bearer auth:

{
  "mcpServers": {
    "unstract": {
      "type": "http",
      "url": "https://<your-deployment>.vercel.app/mcp",
      "authorization": "Bearer <MCP_PUBLIC_KEY>"
    }
  }
}

Endpoints

Development with a local mock

A mock of the Unstract MCP endpoint ships with this repo. It reproduces the real backend's contract (validation rules, the execution_id contract, the one-shot completed-result behaviour) so you can exercise the whole path without credentials.

npm install
npm run build
npm run dev:mock

It prints the MCP endpoint and a ready-to-use bearer token:

MCP endpoint : http://localhost:3000/mcp
Bearer token : mock-client-key

Then:

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mock-client-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The mock returns synthetic extraction results. It exists to validate the proxy, not to replace the real platform.

Local development

npm install
npm test          # 37 unit + integration tests
npm run typecheck
npm run dev

To run against the real Unstract backend, export the env vars and start the server:

export UNSTRACT_API_KEY=<your uuid>
export UNSTRACT_ORG_NAME=<org>
export UNSTRACT_API_NAME=<api name>
export MCP_PUBLIC_KEY=<any secret>
npm run dev

Then:

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MCP_PUBLIC_KEY>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

Protocol details

• Transport: Streamable HTTP, request/response (no SSE).

• JSON-RPC: 2.0. Batch requests are rejected with -32600.

• Protocol revisions: 2025-06-18 (preferred) and 2024-11-05 (accepted).

• Methods: initialize, ping, tools/list, tools/call.

• Errors: JSON-RPC errors are returned with HTTP 200, except authentication which returns a real HTTP 401 with a WWW-Authenticate header.

• Tool errors that the agent can fix are returned as result.isError = true (HTTP 200).

• Unexpected tool errors use JSON-RPC code -32002.

Deployment

This project deploys to Vercel with zero configuration:

• api/index.ts is the serverless function entry point.

• vercel.json pins maxDuration: 60 and rewrites /mcp → /api/index.

• The function is fully stateless — no filesystem, no shared state, so it scales horizontally.

vercel --prod

License

MIT — see LICENSE.

This project is an independent client of the Unstract API. It is not affiliated with or endorsed by Zipstack. Unstract itself is licensed under AGPL-3.0.