Skip to content

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 mcp is a tool named after its operationId (for example get_run, list_workflows, create_workflow, archive_workflow). The list is committed in src/extractit/mcp/tool_inventory.json and CI fails when it drifts from the snapshot (python -m extractit.mcp.inventory --check).
  • Curated: extract_document, diff_versions, explain_field and request_approval.
  • Annotations: readOnlyHint on GET, destructiveHint on DELETE and on operations with x-dx-destructive: true, idempotentHint on PUT/DELETE and on operations that take an Idempotency-Key.
  • Resources: dx://catalog/node-types and dx://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" (or python -m extractit.mcp.bridge --url …) proxies stdio to the endpoint with DX_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).