Using an AI Agent

You can connect an AI assistant or coding agent (Anthropic Claude, Claude Code, OpenAI Codex, or your own) to DocAI Fabric and have it look up projects and documents, read results, and inspect and draft 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.

The quickest start

Tell your agent your deployment's address, for example "connect to our DocAI Fabric at https://your-deployment". Every deployment describes itself to agents at https://your-deployment/llms.txt: which way to work with it for each job, and the exact commands to connect. The agent reads it and walks you through the rest, which is usually signing in once in your browser. The sections below explain each way of connecting, for when you set it up yourself.

Connecting an agent

DocAI Fabric has a built-in MCP server. MCP (Model Context Protocol) is the standard that AI assistants such as Anthropic Claude and OpenAI Codex use to work with other applications. The server runs inside the product, so there is nothing to install. Its address is your deployment's address followed by /mcp, for example https://app.docaifabric.com/mcp. You can copy it, with steps for each assistant, from Agents & API, on the Agents (MCP) tab. The quickest way there is the Claude · Codex button at the top of the in-app Assistant panel: pick your assistant and the page opens on its steps. It is shown to everyone who may connect an agent.

There are three ways to connect an agent. They are listed on that tab in the same order:

Way	Who it suits	What the agent can do
Sign in with the server URL (recommended)	Anyone allowed to connect agents. Nothing to create first.	What the person who connected it can do
Registered agent with limited permissions	An administrator who wants to cap an agent	The person's permissions, never beyond the ones set for the agent
API key, without sign-in	Automation with nobody to sign in, and agents that cannot sign in with OAuth	A personal key: what the person who created it can do, never beyond the key's permissions. An integration key: the key's permissions

Pick one. If a person will be there to sign in, sign in with the server URL: there is nothing to create, and the agent can never do more than that person. Register an agent only when an administrator wants to cap what an agent may do for everyone who connects it. Use an API key only when nobody will sign in, and give it the smallest set of permissions and projects the job needs.

Who may connect an agent. Connecting one, by URL or through a registered agent, and creating a personal API key both need the Create personal API keys and connect agents permission (credential.manage_own). The built-in Admin and Designer roles hold it; Supervisor, Reviewer, Front Office Operator, User Manager and Security Auditor do not, and an administrator can add it to a custom role. Without it the sign-in page refuses, and the Agents & API page is not shown. Taking the permission away pauses every agent the person connected and every personal key they created, until it is given back. Registering an agent and creating an integration key need Manage integration keys and agents (credential.manage_integration), which only the built-in Admin role holds.

The assistant in DocAI Fabric can walk you through any of these; ask it how to connect yours. It does not create API keys or register agents itself: those secrets are shown once, and they never pass through a conversation.

Sign in with the server URL

Paste the server URL into your assistant. Each person signs in to DocAI Fabric with their own account and approves the connection, and the assistant then works as that person.

Anthropic Claude (on the web, Claude Desktop and Cowork):

1. In Claude, open Settings > Connectors and choose Add custom connector.
2. Name it DocAI Fabric, enter your server URL (https://your-deployment/mcp), and leave Advanced settings empty.
3. Choose Add, then Connect.
4. Your browser opens DocAI Fabric. Sign in if you are asked to, read the page that describes the agent, and choose Allow.

On a Claude Team or Enterprise plan, an owner can add the connector once for everyone under Organization settings > Connectors. Each member then only chooses Connect and signs in.

Claude Code. Add the server without a key, then run /mcp inside Claude Code, choose docaifabric and sign in when your browser opens:

claude mcp add --scope user --transport http docaifabric https://your-deployment/mcp

--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.

OpenAI Codex. Add the server, then log in. The second command opens your browser to sign in and approve:

codex mcp add docaifabric --url https://your-deployment/mcp
codex mcp login docaifabric

Other assistants. Any assistant that can add an MCP server by URL and sign in with OAuth works the same way: add the URL as a custom connector or MCP server, connect, sign in and choose Allow.

The agent acts as you. It can do what you can do, in the projects you can reach, and nothing more. It uses your permissions as they are at the moment it acts: if an administrator gives you a new role, the agent can use it straight away, and if a role is taken away, the agent loses it too. Everything it does is recorded in the audit log as you, marked with the agent it came through, so an administrator can tell your own changes from your agent's.

Check the page before you allow. It names the agent, the organization you are signed in to, and the address your browser returns to afterwards, which for Claude is claude.ai. Agents from addresses DocAI Fabric recognizes carry a Verified mark. An agent that runs on your own computer, such as Claude Code or Codex, returns to localhost, and the page warns you about that: any program on your computer could use that name, so allow it only if you started the connection yourself.

Disconnecting is immediate. Open your user menu and choose Connected apps to see every agent you have connected (the menu shows it to anyone who may connect agents, and to anyone who still has a connection), when you connected it and when it was last used. Disconnect stops it at once. A connection also ends by itself if your account is deactivated or you are removed from the organization, and every connection you have ends when you set a new password or reset it by the emailed link: connect again afterwards.

Your deployment has to be reachable from the assistant's servers over the public internet for Claude on the web, Claude Desktop and Cowork. A deployment on a private network or behind a VPN cannot be connected that way, whatever the configuration: use an agent that runs on that network, such as Claude Code or Codex on your computer, instead. It signs in with the server URL the same way.

Registered agent with limited permissions

By default a connected agent has all of the connecting person's permissions. To cap them, an administrator (the Manage integration keys and agents permission) registers an agent with a fixed set of permissions and gets an OAuth client ID and secret for it:

1. In DocAI Fabric, open Agents & API, go to the Agents (MCP) tab and expand Registered Agent With Limited Permissions.
2. Choose Register an agent. Give it a name, choose which assistant will use it, and choose the permissions it may use: pick a role to start from, and expand the permission list only if you want to adjust single permissions. For Anthropic Claude, Claude Code and OpenAI Codex the callback URLs (where the assistant receives the sign-in result) are filled in for you. For Other, enter the callback URL its documentation gives.
3. Copy the client ID and client secret. The secret is shown once.
4. In the assistant, add the custom connector as above, and paste the client ID and secret under Advanced settings. For Codex, see below.

OpenAI Codex builds its callback URL from the server address, and the form works it out from the URL on the page. Add the server to Codex with exactly that URL, or the sign-in is refused:

# ~/.codex/config.toml
[mcp_servers.docaifabric]
url = "https://your-deployment/mcp"

[mcp_servers.docaifabric.oauth]
client_id = "<client ID>"
client_secret_env_var = "DOCAIFABRIC_CLIENT_SECRET"

Codex reads the secret from that environment variable, so it stays out of the file. Export it, then sign in:

export DOCAIFABRIC_CLIENT_SECRET="<client secret>"
codex mcp login docaifabric

An agent connected this way still acts as the person who connects it, with their current permissions, but never with more than the permissions set for the agent. Revoking it disconnects everyone who connected through it and stops every token it holds, rather than waiting for them to expire.

To change a registered agent's name or permissions, choose Edit next to it. Its client ID, secret and callback URLs stay the same, so nothing needs changing in the assistant, and agents already connected through it follow the new permissions on their next call, without reconnecting.

Choosing permissions. The registration form and the API key dialog work the same way: start from one of your organization's roles, built-in or custom, then add or remove single permissions, with a search box to find one quickly. When no role fits, an administrator can create a custom role on the Team → Roles tab (the form links there) and start from it. A role is applied only with the permissions you hold yourself, and the form says how many were left out, since an API key can never carry more than the person who created it.

API key, without sign-in

For automation that runs with nobody to sign in, give the agent an API key. There are two kinds, and the difference matters for anything production depends on:

• A personal key acts as the person who created it, like an agent they signed in: it can do only what they can do now, in the projects they can reach, never beyond the permissions chosen for the key. It stops working if they are deactivated or leave the organization. Anyone allowed to connect agents can create one, which makes it the right key for an agent you run yourself.
• An integration key belongs to the organization. It keeps exactly the permissions and projects chosen for it, whoever leaves. Only an administrator can create one, or turn a personal key into one without changing its secret. Use it for an integration that has to keep running.

The agent sends the key in a request header:

Endpoint	https://your-deployment/mcp
Transport	Streamable HTTP
Authentication	X-API-Key header, or the key as a bearer token

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

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"

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"
      }
    }
  }
}

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.

What an agent gets

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 lookup table or a page, so the agent can send you to exactly the thing it built or found.

The tool list is short and the same for every client. About ten tools: the playbooks and this documentation, list_projects, open_in_gui, find_tools, and three tools that run everything else. The agent asks find_tools for the tool a task needs, in a few words ("change a field description"), and gets back its definition and which of the three runs it: execute_read for reads, execute_write for changes that can be undone before they reach production, and execute_write_destructive for anything that reaches production or cannot be undone, such as publishing or deleting. Reading a playbook with read_skill hands the agent the definitions of the tools that playbook uses, so it can follow the playbook without searching. Every tool your permissions allow is reachable this way; a short list keeps the agent's context small and fits every client's tool limit.

Before you connect, whichever way you choose:

An agent can change configuration, but only in the draft. It can read anything its key or its person allows, and it can reshape a project's classes, fields, validation rules, workflow and lookup tables. 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: an agent connected with the server URL has it only if you do, and a key or a registered agent has it only if it was chosen for them.

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.

Reads can run without asking you. Every tool tells your assistant whether it only reads, and whether it can overwrite or remove something (the standard MCP tool annotations). An assistant that asks before each tool call, such as Claude Desktop, uses this to let reads through execute_read run straight away while still asking before a change. Approvals are given per kind of action, not per tool: allowing execute_write always covers changes that can be undone, while execute_write_destructive asks each time. To change which tools ask, open the connector's tool permissions in your assistant: in Claude, Settings > Connectors, then DocAI Fabric. Permissions set earlier for individual tools such as get_transaction no longer apply: those tools are now reached through the three above.

It can submit, re-run, resume and review transactions. Submitting is described below. Reading them is fine: listing, statuses, extracted values, review issues. read_document returns each page as an image, so the agent compares a value with the page itself, not with the OCR text. With the transaction.rerun permission, rerun_transactions re-runs transactions, one document of a transaction, or a whole Playground or Evaluation dataset, and the agent can wait for the results and fetch the export files. Fetching an export file is a read, so your assistant does not ask you first: a text file (JSON, CSV, TSV, XML, TXT) of up to 64 KB comes back as text, and any other file as a download link that works for 15 minutes, needs no sign-in and opens only that file. To check what many transactions delivered, get_export_files reads the text files of up to 100 of them in one call. Re-running a completed production transaction replaces its reviewed results and sends its exports and webhooks again, so your assistant asks you before every call. With the transaction.resume permission, resume_transaction finishes a failed transaction: it runs the failed step again or carries on from a later one, one transaction at a time, and get_transaction_activity tells the agent why it failed and where it can resume. A resume in production sends the work on to review or export, so your assistant asks you first. Reviewing is described below.

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 Agents & API → 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.

Processing documents with your assistant

Ask your assistant to put documents through a project and it submits them, either by giving you an upload link (an assistant that can run commands uploads the files itself; otherwise you drop them on the upload page) or by importing what one of the project's import connectors finds. Submitting to Production is live work, so your assistant asks you first; to try a project out, ask it to use the Playground.

When it submits, it tells you what the project will do with the documents: which Review steps may stop them, which files the Export step writes, and which system a webhook notifies. What happens next depends on what you asked for:

• Just submit them. It confirms they are in and stops. The results go wherever the project sends them, such as your ERP.
• Bring back the results. It waits for processing to finish and fetches the export files, and tells you when an export failed.
• Tell me if anything needs review. When a Review step stops a transaction, it gives you the review link. Review it in the app, or ask your assistant to review it with you, as described below.

A review can take hours, and an assistant cannot wait that long in a conversation. When it needs the results of a transaction that is waiting for a review, it says so and stops; tell it when the review is done, and it carries on from there.

Reviewing a transaction with your assistant

The workflow's Human Review step pauses a transaction until it is decided. You can work it in the web UI, or have your own assistant work it with you: an assistant you connected with the server URL, or one using your personal API key, reviews as you.

• What it does. It reads the issues the step stopped on and looks at the pages, corrects and confirms extracted values in one call (edit_extracted_data), and takes one of the exits the step offers: Accept, Reject, or one of its Send To actions (decide_review). get_transaction tells it, before it tries, which exits it may take and what blocks the others, such as errors that block Accept.
• On your permissions. It needs what you need in the viewer: changing data for corrections, approving for Accept and Send To, rejecting for Reject. It changes extracted data only while a Human Review step is waiting for the transaction.
• Recorded as you. Every decision is yours, with the assistant named beside it in the transaction's history, and a decision cannot be undone, so your assistant asks you before each one.
• One reviewer at a time. While your assistant works on a transaction it holds it, as the viewer does; a supervisor can take it over.
• Where the step allows it. A Human Review step can be set to take decisions only in the app (its Assistants may decide setting). There your assistant can read the transaction but cannot decide it, nor change its data with its review tools; it is refused with review_step_not_for_assistants (HTTP 403 over the REST API). A script calling the REST field-editing endpoints with your personal API key can still change values at that step, but cannot decide it.

An agent on an integration key cannot decide at a Human Review step: those are for people and the assistants acting for them. It decides at an Agent Review step instead, which waits for an agent rather than a person, with the same tools; when no agent decides in time, that step fails and the transaction leaves by its failure exit, normally to a person. A late decide_review or edit is refused with agent_review_visit_ended and the reason the visit ended (timed_out, step_failed).

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.