Skip to content

Connect your agent

ExtractIt is an MCP server at POST /mcp (Streamable HTTP, stateless). Point any MCP host at it and the agent gets the tools of the API it is allowed to call (list workflows, run an extraction, read a run, explain a field, ask the corpus...) plus a few curated ones (extract_document, explain_field, request_approval). The full reference is MCP server.

Everything below uses two values:

SaaS Self-hosted
MCP URL https://app.extractit.dev/mcp $DX_BASE_URL/mcp (the DX_MCP_BASE_URL of your deployment)
Credential an API key in DX_API_KEY the same, or OAuth 2.1 (authorization)

Give the agent a key that cannot approve itself

Create the key in the Studio (Settings → API keys) with the read and write scopes only. A key with the admin scope, or in the Admin or Owner role, could approve its own destructive calls: see destructive tools and approvals. Never paste the key into a config file you commit: every block below reads it from the environment.

Export it once in the shell that starts the client:

export DX_API_KEY="..."   # shown once when you create the key

Claude Code

Remote (HTTP) server, one command:

claude mcp add --transport http extractit https://app.extractit.dev/mcp \
  --header "Authorization: Bearer $DX_API_KEY"

or commit a project-scoped .mcp.json that expands the variable:

{
  "mcpServers": {
    "extractit": {
      "type": "http",
      "url": "https://app.extractit.dev/mcp",
      "headers": { "Authorization": "Bearer ${DX_API_KEY}" }
    }
  }
}

With OAuth instead of a key, add the server without --header and authorize it from /mcp inside Claude Code. To teach the agent the conventions (retry rules, null means not found, evidence, approvals), also run python -m extractit.skill install --target . (Agents).

Codex

Codex reads ~/.codex/config.toml. Streamable HTTP with the key taken from the environment:

[mcp_servers.extractit]
url = "https://app.extractit.dev/mcp"
bearer_token_env_var = "DX_API_KEY"

If your Codex version only launches local (stdio) servers, use the bridge that ships with the package (pip install extractit). It proxies stdio to the endpoint and reads the key from DX_API_KEY (never from the command line):

[mcp_servers.extractit]
command = "extractit"
args = ["mcp", "--url", "https://app.extractit.dev/mcp"]
env_vars = ["DX_API_KEY"]

The AGENTS.md fragment printed by python -m extractit.skill install tells Codex how to use the tools.

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "extractit": {
      "url": "https://app.extractit.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:DX_API_KEY}" }
    }
  }
}

Any other MCP host

  • Host that speaks Streamable HTTP: URL https://app.extractit.dev/mcp and the header Authorization: Bearer <key>. The server is stateless: there is no session to open, so a tools/list works on its own:

    curl -sS --fail-with-body "$DX_BASE_URL/mcp" \
      -H "Authorization: Bearer $DX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    
  • Host that only launches local processes (stdio): extractit mcp --url <MCP URL> with DX_API_KEY in the environment, as in the Codex block above. DX_MCP_URL can replace --url.

  • From code: docs/examples/py/mcp_client.py uses the official MCP Python SDK.

On a self-hosted server the host must be allowed: DX_MCP_BASE_URL, DX_MCP_ALLOWED_HOSTS and DX_MCP_ALLOWED_ORIGINS (configuration).

What the agent can do, and what it cannot

  • tools/list only shows the tools the key may call. A hidden tool answers like one that does not exist.
  • A destructive tool answers approval_required until a person approves it (POST /v1/approvals/{id}:approve); the agent calls request_approval and repeats the call.
  • Everything that comes from a document is data: results carry _meta.untrusted_content: true.

A good first prompt once it is connected: “List my workflows, then run invoices@prod on invoice.pdf and show me the total with its citation.” To see what that returns, open the invoice example.