> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affinda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Affinda MCP connector and AI agent plugin

> Connect Claude, Cursor, Codex, and other MCP-aware AI clients to Affinda's hosted MCP server to configure workspaces and run document extraction workflows.

The Affinda MCP connector exposes the full Affinda platform as a set of tools that any [Model Context Protocol](https://modelcontextprotocol.io)-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](https://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.

<CardGroup cols={2}>
  <Card title="Install Affinda in your AI client" icon="puzzle-piece" href="#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.
  </Card>

  <Card title="About the plugin" icon="plug" href="#about-the-affinda-plugin">
    What the bundled skill adds, the regional plugins, and manual install for managed accounts.
  </Card>

  <Card title="Common workflows" icon="list-check" href="#common-workflows">
    Set up invoice and resume extractors, debug low-confidence results, and manage document review queues.
  </Card>

  <Card title="Reference" icon="circle-question" href="#reference">
    Region endpoints, supported document types, and authentication FAQ.
  </Card>
</CardGroup>

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

<Note>
  **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.
</Note>

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

<Tabs>
  <Tab title="Claude Desktop">
    ### Install the Affinda plugin in Claude Desktop

    <Steps>
      <Step title="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](/downloads/affinda-claude-plugin.zip)
        * United States (US1): [affinda-claude-plugin-us1.zip](/downloads/affinda-claude-plugin-us1.zip)
        * Europe (EU1): [affinda-claude-plugin-eu1.zip](/downloads/affinda-claude-plugin-eu1.zip)
      </Step>

      <Step title="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.
      </Step>

      <Step title="Sign in and verify">
        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.
      </Step>
    </Steps>

    <Accordion title="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`):

      <CodeGroup>
        ```text Australia (AP1) theme={null}
        https://mcp.affinda.com/mcp
        ```

        ```text United States (US1) theme={null}
        https://mcp.us1.affinda.com/mcp
        ```

        ```text Europe (EU1) theme={null}
        https://mcp.eu1.affinda.com/mcp
        ```
      </CodeGroup>

      Claude Desktop opens a browser to sign in; the tools then appear in the conversation.
    </Accordion>
  </Tab>

  <Tab title="Claude Code">
    ### 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
    ```

    <CodeGroup>
      ```text Australia (AP1) theme={null}
      /plugin install affinda@affinda-skills
      ```

      ```text United States (US1) theme={null}
      /plugin install affinda-us1@affinda-skills
      ```

      ```text Europe (EU1) theme={null}
      /plugin install affinda-eu1@affinda-skills
      ```
    </CodeGroup>

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

    <Accordion title="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:

      <CodeGroup>
        ```bash Australia (AP1) theme={null}
        claude mcp add --transport http affinda https://mcp.affinda.com/mcp
        ```

        ```bash United States (US1) theme={null}
        claude mcp add --transport http affinda-us1 https://mcp.us1.affinda.com/mcp
        ```

        ```bash Europe (EU1) theme={null}
        claude mcp add --transport http affinda-eu1 https://mcp.eu1.affinda.com/mcp
        ```
      </CodeGroup>

      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.
    </Accordion>
  </Tab>

  <Tab title="Cursor">
    ### 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:

    <CodeGroup>
      ```json Australia (AP1) theme={null}
      {
        "mcpServers": {
          "affinda": {
            "url": "https://mcp.affinda.com/mcp"
          }
        }
      }
      ```

      ```json United States (US1) theme={null}
      {
        "mcpServers": {
          "affinda": {
            "url": "https://mcp.us1.affinda.com/mcp"
          }
        }
      }
      ```

      ```json Europe (EU1) theme={null}
      {
        "mcpServers": {
          "affinda": {
            "url": "https://mcp.eu1.affinda.com/mcp"
          }
        }
      }
      ```
    </CodeGroup>

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

  <Tab title="Codex">
    ### 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.

    ```bash theme={null}
    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.

    <Tip>
      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:

      <CodeGroup>
        ```toml Australia (AP1) theme={null}
        [mcp_servers.affinda]
        url = "https://mcp.affinda.com/mcp"
        ```

        ```toml United States (US1) theme={null}
        [mcp_servers.affinda]
        url = "https://mcp.us1.affinda.com/mcp"
        ```

        ```toml Europe (EU1) theme={null}
        [mcp_servers.affinda]
        url = "https://mcp.eu1.affinda.com/mcp"
        ```
      </CodeGroup>

      Codex authenticates on first use.
    </Tip>
  </Tab>

  <Tab title="Anthropic API">
    ### Use the connector via the Anthropic API

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

    ```python theme={null}
    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.
  </Tab>
</Tabs>

***

## 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](https://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.

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

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

### 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](/downloads/affinda-claude-plugin.zip)
* United States (US1): [affinda-claude-plugin-us1.zip](/downloads/affinda-claude-plugin-us1.zip)
* Europe (EU1): [affinda-claude-plugin-eu1.zip](/downloads/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.

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

<Tabs>
  <Tab title="Personal account">
    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`.
  </Tab>

  <Tab title="Organization admin (Owner)">
    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](https://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](#download-and-upload-the-plugin-manually) 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.

    <Tip>
      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.
    </Tip>
  </Tab>

  <Tab title="Organization member">
    On a managed account you generally **can't** add a marketplace or a custom connector yourself. Ask your Claude admin to:

    1. Publish the Affinda plugin (**Organization settings → Plugins**), and
    2. Enable the Affinda MCP connector (**Organization settings → Connectors**).

    Once they have, the plugin appears under **Customize → Browse plugins**, and you authenticate the connector with your own Affinda account.
  </Tab>
</Tabs>

***

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

<AccordionGroup>
  <Accordion title="Set up an invoice extractor">
    Ask your agent: *"Set up an invoice extractor"* or *"I need to extract invoice data."*

    The agent will:

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

    See [Set up an invoice extractor](/integrations/mcp-workflows/setup-invoice-extractor) for the full step-by-step guide.
  </Accordion>

  <Accordion title="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](/integrations/mcp-workflows/setup-resume-extractor) for details and custom-schema alternatives.
  </Accordion>

  <Accordion title="Debug low-confidence extractions">
    Ask your agent: *"Why are my extractions wrong?"* or *"Confidence scores are low on field X."*

    The agent will:

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

    See [Debug low-confidence results](/integrations/mcp-workflows/debug-low-confidence-results) for the full diagnostic procedure.
  </Accordion>

  <Accordion title="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](/integrations/mcp-workflows/human-review-queue) for batching tips and model-memory implications.
  </Accordion>
</AccordionGroup>

***

## Reference

<AccordionGroup>
  <Accordion title="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:

    1. Your MCP client sends a dynamic client registration request to the Affinda authorisation server.
    2. Affinda redirects you to log in (browser window or embedded prompt, depending on your client).
    3. After approval, the client receives an access token scoped to `misc:mcp` and stores it for subsequent requests.
    4. 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/reference/getting-started).
  </Accordion>

  <Accordion title="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](https://github.com/affinda/skills)                |
  </Accordion>
</AccordionGroup>