Affinda MCP connector and AI agent plugin

The Affinda MCP connector exposes the full Affinda platform as a set of tools that any Model Context Protocol-aware AI client can call — Claude Desktop, Claude Code, Cursor, Codex, or your own code via the Anthropic API. Once connected, your AI assistant can create workspaces, configure document types, upload documents, retrieve extracted data, and manage the entire processing lifecycle, all by natural language. The easiest way to add it is the Affinda plugin (from github.com/affinda/skills), which bundles the connector together with a structured skill that teaches the agent how to sequence the tools into real-world workflows. You can also add just the connector if you only want the tools — both are covered below.

Install Affinda in your AI client

Add the Affinda plugin (connector + skill) in Claude Desktop, Claude Code or Codex — or just the connector in Cursor and the API.

About the plugin

What the bundled skill adds, the regional plugins, and manual install for managed accounts.

Common workflows

Set up invoice and resume extractors, debug low-confidence results, and manage document review queues.

Reference

Region endpoints, supported document types, and authentication FAQ.

What you can do

With the Affinda MCP connector connected your AI client can:

Create and configure workspaces — set up OCR modes, splitting, classification, and model memory.
Design extraction schemas — create document types, add fields (text, date, number, table), and attach validation rules.
Upload and process documents — submit files by URL or path and poll until extraction is complete.
Read extracted data — retrieve per-field values and confidence scores for any processed document.
Run a human review queue — list documents awaiting review, inspect extractions, and confirm, reject, or archive them in bulk.
Connect data sources — attach lookup tables (approved vendors, cost centres, skill taxonomies) to fields for validation and auto-population.
Manage integrations — configure export endpoints so confirmed documents push structured data to downstream systems.

The server exposes approximately 75 tools across organisations, workspaces, documents, document types, fields, data sources, matching criteria, integrations, and API token management.

Install Affinda in your AI client

The recommended way to add Affinda is the Affinda plugin. It bundles the hosted MCP connector together with a structured skill — workflow guides and reference material — so your agent knows not just which tools exist but how to sequence them for real jobs like standing up an invoice extractor or running a review queue. The plugin is available for Claude Desktop, Claude Code, and Codex. For clients without a plugin (Cursor, the Anthropic API), or if you want only the server without the skill, add the MCP connector directly by URL — each tab below shows both. However you connect, you authenticate via OAuth 2.1: your client redirects you to log in with your Affinda account and then holds the access token automatically. There is no manual token handling.

Pick the endpoint for your region. Affinda runs three isolated regions and your account lives in exactly one. The rule is simple: your MCP endpoint is the same address you sign in to Affinda from, with app. swapped for mcp.. Connect to the wrong region and you’ll sign in fine but see no workspaces — so if you’re unsure, log in to Affinda and check your browser’s address bar.

Region	You sign in at	MCP endpoint URL
Australia (AP1)	`app.affinda.com`	`https://mcp.affinda.com/mcp`
United States (US1)	`app.us1.affinda.com`	`https://mcp.us1.affinda.com/mcp`
Europe (EU1)	`app.eu1.affinda.com`	`https://mcp.eu1.affinda.com/mcp`

Claude Desktop
Claude Code
Cursor
Codex
Anthropic API

Install the Affinda plugin in Claude Desktop

Download the plugin for your region

Each .zip bundles the connector for one region (same app. → mcp. rule as above):

Australia (AP1): affinda-claude-plugin.zip
United States (US1): affinda-claude-plugin-us1.zip
Europe (EU1): affinda-claude-plugin-eu1.zip

Upload it in Claude Desktop

Open Customise, click + next to Personal plugins, choose Upload plugin, and select the file. It must keep its .zip extension.

Run /mcp (or follow the connector prompt) and sign in with your Affinda account, then start a conversation and type:

“List my Affinda workspaces.”

The assistant should call the list_workspaces tool and return the workspaces in your account. If you see an authentication error, repeat the sign-in step.

Prefer just the MCP server, without the skill?

Open Settings → Integrations (or MCP Servers), click Add integration, and paste the endpoint URL for your region (give it the name affinda):

https://mcp.affinda.com/mcp

Claude Desktop opens a browser to sign in; the tools then appear in the conversation.

Install the Affinda plugin in Claude Code

From inside a Claude Code session, add the marketplace once, then install the plugin for your region:

/plugin marketplace add affinda/skills

/plugin install affinda@affinda-skills

Then run /mcp, complete the browser sign-in with your Affinda account, and ask “List my Affinda workspaces.”

Prefer just the connector, without the skill?

Add only the MCP server (no plugin or skill) with the CLI — use the name and URL for your region:

claude mcp add --transport http affinda https://mcp.affinda.com/mcp

Or add it manually to ~/.claude/settings.json under "mcpServers" (swap the URL for your region’s endpoint from the table above). Claude Code prompts you to sign in the first time a tool is called.

Add the connector in Cursor

Open Cursor settings, navigate to the MCP section, and add a new server entry. Alternatively edit ~/.cursor/mcp.json directly, using the entry for your region:

{
  "mcpServers": {
    "affinda": {
      "url": "https://mcp.affinda.com/mcp"
    }
  }
}

Save and restart Cursor. Cursor prompts you to sign in via OAuth the first time the server connects, after which the Affinda tools appear in the agent panel.

Install the Affinda plugin in Codex

Codex supports plugins (v0.117.0+), so the simplest path is to install the Affinda plugin — it bundles the connector and the skill, just like the Claude Code plugin.

codex plugin marketplace add affinda/skills

Then run /plugins in Codex, select the plugin for your region — Affinda (AP1), Affinda US, or Affinda EU — choose Install, and sign in with your Affinda account when prompted.

Prefer just the MCP server, without the bundled skill? Add the entry for your region to ~/.codex/config.toml (or a project-level .codex/config.toml) instead:

[mcp_servers.affinda]
url = "https://mcp.affinda.com/mcp"

Codex authenticates on first use.

Use the connector via the Anthropic API

If you are calling the Claude API directly, pass the MCP server as part of your request:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[{"role": "user", "content": "List my Affinda workspaces."}],
    mcp_servers=[
        {
            "type": "url",
            "name": "affinda",
            # Use your region's endpoint — see the Regions table above.
            "url": "https://mcp.affinda.com/mcp",
        }
    ],
)
print(response.content)

The Anthropic API MCP connector currently supports tool calls only. MCP prompts and static resources (such as affinda://concepts) are not surfaced through this path. For full feature coverage use one of the desktop or IDE clients.

About the Affinda plugin

The plugin combines the MCP connector with a structured skill — workflow guides and reference material the agent consults when planning multi-step tasks — and is distributed from github.com/affinda/skills. Installing it means your agent knows not just which tools exist, but how to sequence them for common jobs like setting up an invoice extractor or running a review queue. There is a separate plugin per region (affinda, affinda-us1, affinda-eu1); the install tabs above select the right one for you.

Install one regional plugin at a time. Having more than one installed simultaneously exposes duplicate tool sets and makes region selection ambiguous.

The skill is optional. Every tool stands on its own — the skill only adds multi-step workflow guidance on top of the tool descriptions. The “just the MCP server / connector” options in the tabs above give you the tools without it.

Download and upload the plugin manually

If you can’t add a marketplace — for example on a managed account, or if you’d rather not connect GitHub — download the plugin .zip for your region and upload it directly. In Claude Desktop, open Customise → Personal plugins → Upload plugin and select the file (it must keep its .zip extension); then run /mcp and sign in with your Affinda account.

Australia (AP1): affinda-claude-plugin.zip
United States (US1): affinda-claude-plugin-us1.zip
Europe (EU1): affinda-claude-plugin-eu1.zip

Organizations, Teams & Enterprise

On a managed Claude account, governance changes how the plugin and connector get installed. The short version: an admin usually has to make the plugin and the MCP connector available before members can use them.

Claude’s plugin and connector surfaces change often. The paths below were accurate as of May 2026 — check your admin console before rolling out.

Personal account
Organization admin (Owner)
Organization member

Add the affinda/skills marketplace and install the plugin (above), or upload the .zip directly. You can add the MCP connector yourself via Customize → Connectors or claude mcp add.

In Claude Desktop, organizations can’t add public plugin marketplaces. As an Owner / Primary Owner you have two routes:

Fork + sync — fork github.com/affinda/skills into a private org repository, then connect it under Organization settings → Plugins (GitHub sync; public repos aren’t accepted for org marketplaces).
Upload — download the plugin .zip for your region and upload it under Organization settings → Plugins.

Set each plugin’s availability (Installed by default / Available for install / Required / Not available).Then add the Affinda connector under Organization settings → Connectors — only Owners / Primary Owners can add custom connectors. Members authenticate individually once it’s enabled.

On Claude Code (CLI) you can instead allow the public marketplace directly by adding affinda/skills to strictKnownMarketplaces (or extraKnownMarketplaces) in managed settings — no fork required.

Common workflows

The following workflows are available as structured guides inside the plugin skill and as MCP prompts on the server (for clients that support prompts). Each can also be triggered by describing what you want to the agent in plain language.

Set up an invoice extractor

Ask your agent: “Set up an invoice extractor” or “I need to extract invoice data.”The agent will:

Locate your Affinda organisation.
Create a workspace with appropriate OCR mode (digital PDFs vs scanned images) and classification settings.
Create an Invoice document type and bulk-create the standard field schema (invoice number, dates, vendor, line items, totals, currency).
Optionally add validation rules that check totals and line-item sums.
Tell you the workspace is ready to receive uploads.

See Set up an invoice extractor for the full step-by-step guide.

Set up a resume / CV extractor

Ask your agent: “Set up a resume extractor” or “I want to parse CVs.”The agent calls create_recruit_workspace, which provisions a pre-configured “Recruitment” workspace with four document types in a single step: Resume, Job Description, Redacted Resume, and Resume Summary. Classification automatically routes uploads to the right type.See Set up a resume extractor for details and custom-schema alternatives.

Debug low-confidence extractions

Ask your agent: “Why are my extractions wrong?” or “Confidence scores are low on field X.”The agent will:

Read the document type configuration and workspace processing settings.
Sample recent extractions and identify patterns (one field consistently wrong vs all fields on specific documents).
Propose up to three ranked changes — OCR mode first (the most impactful lever), then field-level prompt fixes, then validation rules.
Wait for your approval before making any changes.

See Debug low-confidence results for the full diagnostic procedure.

Run a human review queue

Ask your agent: “Review my documents” or “What’s in my review queue?”The agent lists documents in review state, presents field values and confidence scores, and applies your verdict in bulk:

Confirm — marks extractions as validated and feeds them into model memory.
Reject — flags documents as incorrect and signals the model to avoid similar errors.
Archive — removes documents from the active queue without rejection.
Reassign — moves a document to a different document type and triggers a reparse.

See Human review queue for batching tips and model-memory implications.

Reference

Authentication

Public clients (Claude Desktop, Claude Code, Cursor, Codex) authenticate via OAuth 2.1 with Dynamic Client Registration. You log in with your existing Affinda account credentials; no API keys or JWTs need to be handled manually.The OAuth flow:

Your MCP client sends a dynamic client registration request to the Affinda authorisation server.
Affinda redirects you to log in (browser window or embedded prompt, depending on your client).
After approval, the client receives an access token scoped to misc:mcp and stores it for subsequent requests.
All tool calls carry this token as a Bearer header; the MCP server verifies it locally against Affinda’s JWKS.

Tokens are managed automatically by your MCP client — there is nothing to rotate or store yourself.

Regions

Affinda operates in three isolated regions and your account lives in exactly one. Your MCP endpoint is the same address you sign in to Affinda from, with app. swapped for mcp.:

Region	You sign in at	MCP endpoint
Australia (AP1)	`https://app.affinda.com`	`https://mcp.affinda.com/mcp`
United States (US1)	`https://app.us1.affinda.com`	`https://mcp.us1.affinda.com/mcp`
Europe (EU1)	`https://app.eu1.affinda.com`	`https://mcp.eu1.affinda.com/mcp`

If you’re unsure which region your account uses, log in to the Affinda app and check the URL in your browser’s address bar. Connecting to the wrong region authenticates successfully but returns no workspaces.

Supported document types

The MCP connector works with any document type configured in your Affinda account. Common use cases include:

Invoices — vendor invoices, supplier bills, expense receipts
Resumes and CVs — candidate applications, job descriptions
Contracts — agreements, NDAs, statements of work
Identity documents — passports, driver licences, ID cards
Financial documents — bank statements, payslips, tax forms
Custom document types — any structured or semi-structured document type you define in Affinda

Document formats supported by the underlying platform: PDF, DOC, DOCX, XLSX, ODT, RTF, TXT, HTML, PNG, JPG, TIFF, and JPEG.

Available MCP tools

The server exposes approximately 75 tools organised by resource domain:

Domain	Example tools
Organisations	`list_organizations`, `get_organization`
Workspaces	`create_workspace`, `update_workspace`, `list_workspaces`
Documents	`upload_document`, `get_document`, `get_document_extraction`, `confirm_documents`, `reject_documents`
Document types	`create_document_type`, `list_document_types`, `create_recruit_workspace`
Fields	`bulk_create_fields`, `create_field`, `update_field`, `delete_field`
Validation rules	`create_validation_rule`, `delete_validation_rule`
Data sources	`create_data_source`, `add_value_to_data_source`, `bulk_add_values_to_data_source`
Integrations	`create_integration`, `update_integration`, `list_integrations`
API tokens	`create_api_token`, `list_api_tokens`, `revoke_api_token`

For the full tool catalog with parameter details, see the API Reference.

Troubleshooting

Symptom	Likely cause	Fix
Authentication prompt does not appear	Client is not requesting OAuth flow	Re-add the connector; ensure your client supports OAuth 2.1 DCR
`list_workspaces` returns empty	Authenticated as the wrong account or wrong region endpoint	Sign out, remove the connector, and re-add with the endpoint matching your account’s region
Tool calls return 401	Expired or revoked access token	Disconnect and reconnect the integration to trigger a fresh OAuth login
`wait_for_document_processing` times out	Document is large or the processing queue is busy	Call `get_document` to poll the status manually; the 300-second cap will have been reached
Agent picks the wrong tool	Tool descriptions don’t match user intent	File a bug at github.com/affinda/skills

Documentation Index

Install Affinda in your AI client

About the plugin

Common workflows

Reference

​What you can do

​Install Affinda in your AI client

​Install the Affinda plugin in Claude Desktop

​Install the Affinda plugin in Claude Code

​Add the connector in Cursor

​Install the Affinda plugin in Codex

​Use the connector via the Anthropic API

​About the Affinda plugin

​Download and upload the plugin manually

​Organizations, Teams & Enterprise

​Common workflows

​Reference

What you can do

Install Affinda in your AI client

Install the Affinda plugin in Claude Desktop

Install the Affinda plugin in Claude Code

Add the connector in Cursor

Install the Affinda plugin in Codex

Use the connector via the Anthropic API

About the Affinda plugin

Download and upload the plugin manually

Organizations, Teams & Enterprise

Common workflows

Reference