MCP (Model Context Protocol) #

BonsAI exposes its platform to AI assistants — Claude, and any other MCP-compatible client — through tofu-external-mcp, a hosted MCP server. Once connected, an assistant can read your invoices, bills, bank statements, and entity settings, and (for the write tools) create entities, upload documents, and trigger extractions — all scoped to your own organization and permissions, using the same sign-in you already use for BonsAI.

What is MCP? #

MCP is an open protocol that lets an AI assistant call a fixed set of well-defined tools exposed by a server, instead of guessing at a REST API or scraping a UI. Each tool has a name, a description, and a typed input/output schema — the assistant reads the schema, decides which tool answers the user’s question, calls it with structured arguments, and gets back structured data (not HTML, not free text it has to parse). You describe what you want in plain language; the assistant picks the right tool(s) and args for you.

What is tofu-external-mcp? #

tofu-external-mcp is BonsAI’s MCP server for external, customer-facing use. It forwards every call to bonsapi (BonsAI’s own API) using your signed-in identity — every tool call is authenticated with your Clerk OAuth token and scoped to exactly what your account can already see and do in the BonsAI app. There is no separate “MCP admin” access and no way to reach another organization’s data through it.

• Read tools — invoices, bills, direct expenses, bank statements, documents, entities, integrations, knowledge, usage/billing. Safe to call freely; nothing is changed.
• Write tools — create an entity, update entity settings, upload a document, create/re-trigger an extraction, add a knowledge card, manage entity members and org roles. Each one is gated by the same permission BonsAI’s own UI enforces (e.g. you need Entity:Update to change entity settings) — there’s no separate “MCP is more permissive” path.

See Tools reference for the full list, with input/output for each.

Connecting from Claude #

Claude Code (CLI) #

Add an entry to your project’s .mcp.json (or run claude mcp add):

{
  "mcpServers": {
    "tofu-external-mcp": {
      "type": "http",
      "url": "https://mcp.gotofu.com"
    }
  }
}

The first time Claude Code calls a tool, it opens a browser window for you to sign in with your BonsAI account (standard OAuth — the same login you use for the BonsAI web app). After that, the session stays authenticated; no API key or token to copy anywhere.

Claude.ai (web / desktop) #

In Claude’s settings, go to Connectors → Add custom connector, and enter the same URL (https://mcp.gotofu.com). Claude will walk you through the same browser sign-in, then the tools become available in any chat.

Example #

Once connected, just ask in plain language — Claude figures out which tools to call:

“What AP bills are still pending review for my Acme Corp entity?”

Behind the scenes, Claude will typically:

1. Call whoami (no input) to confirm the connection and see which entities you can access.
2. Call list_entities to find the entity id matching “Acme Corp”.
3. Call list_extractions with {"entity_id": "<id>", "types": ["AP_BILL"], "statuses": ["NEEDS_REVIEW"]} to get the matching bills.
4. Call get_invoice on any of those to show you the actual amounts, vendor, and line items.

You never write any of those calls yourself — that’s the point of MCP. The tools reference below exists for when you want to know exactly what Claude is doing, or you’re building your own MCP client instead of using Claude.

Auth model, in short #

• Sign-in, not a static secret. Every call carries your own Clerk-issued OAuth token, refreshed automatically by your MCP client. There’s no long-lived API key to store or leak.
• Same permissions as the app. If your BonsAI role can’t do something in the web app, the matching MCP tool denies it too — with a clear error, not a silent no-op.
• Org-scoped. You only ever see and change data in your own organization.