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/mcpand the headerAuthorization: Bearer <key>. The server is stateless: there is no session to open, so atools/listworks 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>withDX_API_KEYin the environment, as in the Codex block above.DX_MCP_URLcan replace--url. - From code:
docs/examples/py/mcp_client.pyuses 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/listonly shows the tools the key may call. A hidden tool answers like one that does not exist.- A destructive tool answers
approval_requireduntil a person approves it (POST /v1/approvals/{id}:approve); the agent callsrequest_approvaland 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.