---
name: chainfill-connect
description: Connect an AI client to Chainfill's hosted MCP server with browser OAuth, or repair a connection that fails. Use when the user wants to use Chainfill from Claude, ChatGPT, Codex, Claude Code, Cursor, VS Code or Gemini CLI, or when Chainfill tools are missing or return authorization errors.
---

# Connect to Chainfill

Chainfill's MCP server is a remote Streamable HTTP server with OAuth:

```
https://api.chainfill.ai/mcp
```

## Steps

1. Add a custom remote MCP server named `Chainfill` with the URL above. Add no headers, token, API key or local command.
2. Start the client's Connect or Authenticate action. It opens Chainfill in the browser.
3. The user signs in as usual (password, two-factor or SSO).
4. On the consent screen the user chooses the teams (if they have more than one) and the access level: **Read only**, **Read and edit** (the user approves each change) or **Read and edit without asking**. Partners and Chainfill staff do not choose teams: their connection covers every team they can open. Then they choose **Approve connection**.
5. The browser returns to the client. The client stores and refreshes the tokens itself.

Per client:

- **Claude, Claude Desktop, Cowork**: Customize > Connectors > + > Add custom connector, enter the URL, then Connect. On Team and Enterprise plans an Owner first adds the connector under Organization settings > Connectors.
- **Claude Code**: install the Chainfill plugin (`/plugin marketplace add https://www.chainfill.ai/claude-plugins/marketplace.json`, then `/plugin install chainfill@chainfill`), which adds the server and these skills; or only the server with `claude mcp add --transport http --scope user chainfill https://api.chainfill.ai/mcp`. Then run `/mcp`, select Chainfill and sign in.
- **Codex CLI**: `codex mcp add chainfill --url https://api.chainfill.ai/mcp`, then `codex mcp login chainfill`.
- **ChatGPT**: turn on Developer mode, add a connector with the URL and approve in the browser.
- **Cursor**: add `{"mcpServers": {"chainfill": {"url": "https://api.chainfill.ai/mcp"}}}` to `~/.cursor/mcp.json`, then start it and complete OAuth.
- **VS Code with GitHub Copilot**: MCP: Add Server > HTTP > Global, enter the URL, then start it from MCP: List Servers.
- **Gemini CLI**: `gemini mcp add --transport http --scope user chainfill https://api.chainfill.ai/mcp`; if the browser does not open, run `/mcp auth chainfill`.

## Check that it works

Call a harmless read tool that needs no ids, such as `document.exceptions` or `knowledge.search` with a short query. (Some tools, like `doctype.list`, also ask for your company id.) In Chainfill the connection then shows as Active under Settings > Connected AI clients.

## If it does not work

- **Consent screen says new connections are unavailable, or the Connected AI clients page is empty**: remote MCP is not switched on for this team. Ask the user to contact their Chainfill contact or support@chainfill.ai.
- **The client asks for a token, key or secret**: stop. Use its OAuth or Authenticate action instead. Never ask the user to paste a credential.
- **A tool that changes something is missing**: the user approved read access, or their role does not allow it (the tool list only shows what their role allows). With read access, they can reconnect and choose Read and edit.
- **"Unavailable while impersonating"**: the user is viewing Chainfill as someone else. They must switch back to their own account first.
- **Partner accounts** connect every customer their partner is linked to, including customers linked later. "Your partner account has no customers yet" means no customer is linked; ask Chainfill to link one.
- **Viewing Chainfill as someone else** blocks connecting. Stop viewing as that person in Chainfill, then sign in again.
- **A change returns `not_confirmed`**: the user declined the confirmation form, so nothing changed. Ask what they want instead; do not run it again.
- **A tool returns `file_ref_not_supported`**: the hosted connection cannot read files from the user's computer. Ask the user to upload the file in the Chainfill app instead.
- **A tool returns `not_permitted` or another permission error**: the user's role in that team does not allow it (some operator tools run for Chainfill staff only). Explain this; do not retry with other tools to get around it.
- **Multiple teams connected**: every tool needs the `team` argument. Ask the user which team when it is not obvious.
- **A `find_team` tool is listed**: the connection covers every team the user can open (partners, Chainfill staff). Look the team up by name with `find_team` and pass its id as `team`. While the user has a team open in Chainfill, a call without `team` acts in that open team; with no team open, `team` is required.

To revoke: in Chainfill, Settings > Connected AI clients > Revoke, and remove the connector in the client too.