MCP server
ExtractIt exposes its API as an MCP server at POST /mcp (Streamable HTTP, stateless: no
session, every request stands alone; JSON responses).
Tools
- Generated: every operation of the OpenAPI document tagged
mcpis a tool named after itsoperationId(for exampleget_run,list_workflows,create_workflow,archive_workflow). The list is committed insrc/extractit/mcp/tool_inventory.jsonand CI fails when it drifts from the snapshot (python -m extractit.mcp.inventory --check). - Curated:
extract_document,diff_versions,explain_fieldandrequest_approval. - Annotations:
readOnlyHinton GET,destructiveHinton DELETE and on operations withx-dx-destructive: true,idempotentHinton PUT/DELETE and on operations that take anIdempotency-Key. - Resources:
dx://catalog/node-typesanddx://docs/{tool}.
Tools call the API in process with the caller's identity: scopes, roles, row-level security,
rate limits and RFC 9457 errors are the API's. An API error reaches the agent as a tool error with
status, code, recovery and retry_after.
Scopes
tools/list only shows the tools the credential may call (scopes ∩ role). A hidden tool answers
exactly like a tool that does not exist. With OAuth, a tool that a wider scope would allow answers
403 insufficient_scope (step-up, see authorization).
Destructive tools and approvals
A destructive tool without approval_id returns approval_required. The agent calls
request_approval(tool, arguments, summary); a person with the Admin or Owner role (or a key with
the admin scope) approves it with POST /v1/approvals/{id}:approve; the agent repeats the call
with approval_id. The approval binds the SHA-256 of the RFC 8785 canonical arguments, is valid
10 minutes and is consumed atomically: errors approval_pending, approval_mismatch,
approval_consumed, approval_expired, approval_rejected, each with recovery.
Agent keys
The approval is only a barrier if the agent's key has neither the admin scope nor the
Admin role. Create agent keys with read/write only.
Content safety
Every result carries _meta.untrusted_content: true; the server instructions and tool
descriptions say that document text is data. Outputs over 256 KiB are replaced by
{truncated: true, results_url, …}. Invalid API keys are limited to 10 per minute per address
(then 429). Host and Origin must be in the allow lists (DX_MCP_BASE_URL,
DX_MCP_ALLOWED_HOSTS, DX_MCP_ALLOWED_ORIGINS).
Connecting
- API key:
Authorization: Bearer $DX_API_KEY. - OAuth 2.1: see authorization.
- stdio hosts:
extractit mcp --url "$DX_BASE_URL/mcp"(orpython -m extractit.mcp.bridge --url …) proxies stdio to the endpoint withDX_API_KEY.
# SPDX-License-Identifier: Apache-2.0
# expect: request_approval
"""Call the MCP endpoint with the official MCP Python SDK and an API key."""
import asyncio
import os
import httpx2
from mcp.client.client import Client
from mcp.client.streamable_http import streamable_http_client
async def main() -> None:
headers = {"Authorization": f"Bearer {os.environ['DX_API_KEY']}"}
async with (
httpx2.AsyncClient(headers=headers) as http,
Client(streamable_http_client(f"{os.environ['DX_BASE_URL']}/mcp", http_client=http)) as mcp,
):
tools = await mcp.list_tools()
print(sorted(t.name for t in tools.tools))
asyncio.run(main())
Configuration
| Variable | Meaning |
|---|---|
DX_MCP_ENABLED |
0 disables the endpoint (default on). |
DX_MCP_BASE_URL |
Canonical public URL of the API; the token audience is <base>/mcp. |
DX_MCP_ISSUER |
Issuer of the IdP (enables OAuth). |
DX_MCP_JWKS_URI |
JWKS of the IdP (default: Keycloak path or /.well-known/jwks.json). |
DX_MCP_AUTHORIZATION_SERVERS |
Advertised authorization servers (default: the issuer). |
DX_MCP_ALLOWED_HOSTS, DX_MCP_ALLOWED_ORIGINS |
Extra allowed Hosts and Origins. |
Tagging operations (for contributors)
A ticket that adds an endpoint useful to agents adds tags=["mcp"] to its route (plus
openapi_extra={"x-dx-destructive": True} if it destroys data without being a DELETE), regenerates
openapi/openapi.json and the inventory, and adds its documentation page and a runnable example
(see Contributing to the docs).