Using an AI Coding Agent

You can point an AI coding agent (Claude Code, OpenAI Codex, or your own) at DocAI Fabric and have it submit documents, read results, and inspect a project's configuration. This page is what such an agent needs to know, and it is written to be read by one: hand it this URL and it has enough to start.

Connecting over MCP

The quickest route for an agent that speaks MCP is the built-in server. It runs inside the product, so there is nothing to install:

Endpoint	https://your-deployment/mcp
Transport	Streamable HTTP
Authentication	X-API-Key header

To add it to Claude Code:

claude mcp add --scope user --transport http docaifabric https://your-deployment/mcp \
  --header "X-API-Key: your-api-key"

--scope user registers the server for every folder you work in. Without it the agent finds DocAI Fabric only in the directory you ran the command from.

To add it to Codex, put this in ~/.codex/config.toml:

[mcp_servers.docaifabric]
url = "https://your-deployment/mcp"
bearer_token_env_var = "DOCAIFABRIC_API_KEY"

Codex reads the named environment variable when it connects and sends it as a bearer token, so your key stays out of the configuration file. Export it in the shell you start Codex from:

export DOCAIFABRIC_API_KEY="your-api-key"

Codex also accepts a static header if you prefer to be explicit, using http_headers = { "X-API-Key" = "your-api-key" } in place of bearer_token_env_var. The endpoint accepts either.

Or, in a client that takes a configuration file:

{
  "mcpServers": {
    "docaifabric": {
      "type": "http",
      "url": "https://your-deployment/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Connecting a hosted assistant

Claude, Cowork and Claude Desktop add an MCP server through a connector dialog that takes a URL and, under Advanced settings, an OAuth client ID and secret. There is no field for a request header, so these assistants cannot use an API key at all. They use OAuth instead.

To set one up:

1. In DocAI Fabric, open API & Agents, go to the MCP for agents tab and find Hosted Assistants.
2. Choose Register an agent. Give it a name, check the redirect URL your assistant's documentation specifies, and pick the permissions it should have.
3. Copy the server URL, client ID and client secret. The secret is shown once.
4. In your assistant, add a custom connector with that URL, and paste the client ID and secret under Advanced settings.

The first time the assistant connects, your browser opens a page in DocAI Fabric listing the agent and the exact permissions it is asking for. Nothing is issued until you approve it.

Two things worth knowing:

The agent gets your permissions, not the agent's. The permissions chosen at registration are a ceiling. What the agent actually receives is that list narrowed to what the person authorising it holds, so connecting as an administrator does not make the agent one. The agent acts as that person, and its actions are recorded against their account.

Revoking is immediate. Revoking an agent under Hosted Assistants disconnects it and stops every token it currently holds, rather than waiting for them to expire.

Your deployment also has to be reachable from the assistant's servers over the public internet. A deployment on a private network or behind a VPN cannot be connected this way, whatever the configuration: use an agent you run yourself, with an API key, instead.

What this gives an agent that the REST API does not:

• Tools shaped like intentions, not endpoints. "List the document classes in this project" is one tool call with the project's rules enforced behind it, rather than a settings document to fetch, edit and write back.
• Playbooks. list_skills names the procedures the product knows (setting up a project, designing a workflow, writing validation rules), and read_skill loads one. They travel with your deployment, so they match the version you are running.
• This documentation, searchable in place through grep_documentation and read_documentation.
• Links into the app. open_in_gui returns a link to a transaction, a document or a field in the Transaction Viewer, a validation rule in its editor, a workflow step's settings, a catalog or a page, so the agent can send you to exactly the thing it built or found.

The tool list starts small and grows. An agent is first shown a core set of tools plus the playbooks. Reading a playbook with read_skill makes the tools it uses available, and load_tools adds a named group when no playbook fits. The server tells the client when the list has changed (the standard MCP tools/list_changed notification), so the agent sees the new tools without reconnecting. This keeps the agent's context small and keeps a deployment within the tool limits some models impose. It works through a session the server issues at connection (Mcp-Session-Id); a client that does not keep sessions is given the full list instead.

Two things to know before you connect:

It needs a scoped key. The endpoint accepts only keys created with an explicit set of permissions. Older keys carry full access to everything in the tenant, which is more than an agent should hold, and are refused. Create one on the API & Agents → API Keys tab and give it only what the agent's job needs.

Your agent has to run somewhere that can reach the deployment. An agent running on your own machine can use a local address. One that runs in someone else's cloud needs an address published on the internet.

An agent can change configuration, but only in the draft. It can read anything its key allows, and it can reshape a project's classes, fields, validation rules, workflow and catalogs. Those changes land in the project's draft and reach production only when a person publishes, which is the boundary that makes it reasonable to let an agent propose a configuration at all. Publishing needs the project.publish permission, which is in no ready-made preset.

Deleting takes two calls. The first returns a description of exactly what would be removed and does not remove it. The agent is expected to show you that and get your agreement before calling again with the token it was given. Tokens are single-use and short-lived.

Retries are safe on anything that creates. Pass an idempotency_key you choose, and repeating the call returns the original result instead of making a second class, field or rule.

It cannot run or edit transactions yet. Reading them is fine: listing, statuses, extracted values, review issues. Submitting, re-running and editing results are coming.

Start an agent by having it call list_skills. The playbooks carry the order and the pitfalls that individual tool descriptions cannot.

What an agent works with

Everything on this surface is the REST API, so nothing here is specific to any one agent product:

• Authentication with an X-API-Key header. Keys are minted per tenant under API & Agents → API Keys.
• Process Documents to submit files and start processing, in one call or several.
• Checking status, including long-polling so an agent waits rather than spins.
• Webhooks to be told when a transaction finishes, instead of polling for it.
• Accessing OCR and field data to read the extracted values, their confidence, and where on the page each came from.
• Datasets to keep an agent's experiments in Playground rather than Production.

Working safely

An agent that can call the API can change real configuration and real data, so decide up front what it is allowed to touch.

Give it its own API key. Never reuse a key an integration depends on. A key you can revoke without breaking anything else is what lets you stop an agent quickly.

Keep experiments in the Playground dataset. Documents an agent submits while it is finding its feet do not belong in Production alongside real work. See Datasets.

Understand the draft and published split. Configuration changes land in the project's draft and reach production only when someone publishes. That boundary is what makes it reasonable to let an agent propose a configuration at all: the change is visible and reversible until a person publishes it. See Versions and Publishing.

Review before publishing. Read the draft changes yourself. An agent that has misunderstood a document class will produce a configuration that looks plausible and extracts the wrong things.

Getting a human to look at a transaction

An agent cannot review a transaction: review is a human step, and it happens in the DocAI Fabric interface. When results need checking, send the person to the transaction in the web UI and let them work it there. The workflow's Review step is what pauses a transaction until they do.

Where to start

1. API Quick Start, which is three steps end to end.
2. Process Documents for the complete submit-and-retrieve reference.
3. API Overview for how the endpoints are organized.