# MCP server > Connect Claude, ChatGPT, Cursor and other MCP clients and agents to a company's books, safely. Source: https://app.getoatmilk.com/docs/mcp Oatmilk runs a [Model Context Protocol](https://modelcontextprotocol.io) server, so AI assistants can work in Oatmilk with the same actions and the same permissions as the person using them. An assistant can find what needs a receipt, add one, reconcile a transaction or draft an invoice, and it can never do more than that person could in the app. ``` https://app.getoatmilk.com/api/mcp ``` > [!TIP] > Not a developer? [Connect your AI app](https://app.getoatmilk.com/docs/connect.md) walks you through Claude and ChatGPT in about a minute, with no code. ## Connect a client Most clients sign in with OAuth: add the address, sign in to Oatmilk when the client asks, and approve what it may do. Clients that can't sign in can send an API key as a bearer token instead. **Claude.** Add to Claude opens Claude's Add custom connector form with Oatmilk filled in. You can also add a custom connector with this address in Settings › Connectors. Sign in to Oatmilk when asked. Cards open right in the chat on the web, desktop and phone apps. [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Oatmilk&connectorUrl=https%3A%2F%2Fapp.getoatmilk.com%2Fapi%2Fmcp) ```text https://app.getoatmilk.com/api/mcp ``` **ChatGPT.** Turn on Developer mode in Settings › Security and login, open Plugins, choose + and add this address. Sign in to Oatmilk when ChatGPT asks. For the guides in desktop Work mode or Codex, download and unzip the plugin, run codex plugin marketplace add ./oatmilk from its parent folder, then restart the app. In Plugins Directory, choose Oatmilk and install. [Download the Oatmilk plugin](https://app.getoatmilk.com/api/plugin/oatmilk.zip) ```text https://app.getoatmilk.com/api/mcp ``` **Claude Code.** Install the Oatmilk plugin, which adds the server and guides for receipts, bookkeeping, year-end, company details and contractor hours. Then run /mcp in Claude Code to sign in. ```bash claude plugin marketplace add https://app.getoatmilk.com/api/plugin/marketplace.json claude plugin install oatmilk@oatmilk ``` **Codex.** Add the server from your terminal. The second command signs you in to Oatmilk. For the guides too, download and unzip the plugin, then run codex plugin marketplace add ./oatmilk and codex plugin add oatmilk@oatmilk from its parent folder. Restart Codex and sign in when asked. [Download the Oatmilk plugin](https://app.getoatmilk.com/api/plugin/oatmilk.zip) ```bash codex mcp add oatmilk --url https://app.getoatmilk.com/api/mcp codex mcp login oatmilk ``` **Cursor.** Add to Cursor asks you to confirm, or add the server to your project's or your global MCP settings. Cursor asks you to sign in the first time. [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=oatmilk&config=eyJ1cmwiOiJodHRwczovL2FwcC5nZXRvYXRtaWxrLmNvbS9hcGkvbWNwIn0%3D) ```json title=".cursor/mcp.json" { "mcpServers": { "oatmilk": { "url": "https://app.getoatmilk.com/api/mcp" } } } ``` **Gemini CLI.** Add the server to your Gemini CLI settings. Gemini CLI asks you to sign in the first time. ```json title="~/.gemini/settings.json" { "mcpServers": { "oatmilk": { "httpUrl": "https://app.getoatmilk.com/api/mcp" } } } ``` **opencode.** Add the server to your project's or your global opencode settings. opencode asks you to sign in the first time it uses a tool, or run opencode mcp auth oatmilk. To use an API key instead, add headers with Authorization set to Bearer {env:OATMILK_API_KEY}. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "oatmilk": { "type": "remote", "url": "https://app.getoatmilk.com/api/mcp", "enabled": true } } } ``` **Hermes Agent.** Add the server to your Hermes settings, keep the key in ~/.hermes/.env, then start Hermes or run /reload-mcp. The key's permissions decide which tools work. ```yaml title="~/.hermes/config.yaml" mcp_servers: oatmilk: url: "https://app.getoatmilk.com/api/mcp" headers: Authorization: "Bearer ${OATMILK_API_KEY}" enabled: true ``` **VS Code.** Add to VS Code asks you to confirm, or add the server to your workspace. VS Code asks you to sign in the first time it starts. [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22oatmilk%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.getoatmilk.com%2Fapi%2Fmcp%22%7D) ```json title=".vscode/mcp.json" { "servers": { "oatmilk": { "type": "http", "url": "https://app.getoatmilk.com/api/mcp" } } } ``` **Oatmilk CLI.** For an agent that only starts local commands: the Oatmilk command line serves the same tools over stdio, signed in with oatmilk login or OATMILK_API_KEY. ```json title="mcp.json" { "mcpServers": { "oatmilk": { "command": "npx", "args": [ "-y", "@getoatmilk/cli", "mcp" ] } } } ``` **With an API key.** For a client or your own agent that can't sign in, send an API key as a bearer token. The key's permissions decide which tools work. ```json title="mcp.json" { "mcpServers": { "oatmilk": { "url": "https://app.getoatmilk.com/api/mcp", "headers": { "Authorization": "Bearer ${OATMILK_API_KEY}" } } } } ``` ## Interactive cards In apps that show them (Claude, ChatGPT, VS Code and others that support MCP Apps), some tools open a card right in the chat instead of answering in text. Each card does one job, checks the same permissions as the app, and saves through the ordinary tools, so a client without cards can still do everything a card does. | Card | Tool | What it does | | --- | --- | --- | | Needs you | `oatmilk_needs_you` | Everything waiting on the person, with one action each that opens the right card or page. | | Add receipts | `oatmilk_add_receipts` | Take a photo or choose receipts, optionally for a purchase that needs one, and watch Oatmilk read them. | | Questions from Oatmilk | `oatmilk_answer_questions` | Oatmilk's questions about charges, answered one at a time. | | File documents | `oatmilk_file_documents` | Upload any document, see what Oatmilk thinks it is, and file it in the right place. | | Company profile | `oatmilk_company_profile` | See the company's details and where each came from; administrators edit them or fill them from incorporation papers. | | Tax preparation | `oatmilk_tax_prep` | The year-end (T2) or GST/HST checklist for a period, with the next step and official deadlines. | | Compliance deadlines | `oatmilk_compliance_deadlines` | Upcoming filing and remittance deadlines, each with Mark done, Snooze a week or Not applicable. | | Your hours | `contractor_log_hours` | A contractor's own timesheet: log time and send it for review. | Ask for what you want, such as "add these receipts" or "what's due this month?", and the assistant opens the right card. When a step needs a person in Oatmilk, the card links straight to that page. In ChatGPT, files you attach to the chat go straight in: `oatmilk_upload_receipts` adds receipts and `oatmilk_upload_documents` adds anything else Oatmilk files, then the same cards open to show them. Cards there can also pick files from your ChatGPT library. ## Insights Map Use the same world map from an external agent: `accounting_insights_map_get` searches layers, dates, currencies, transaction types, places and visible bounds, and `accounting_insights_map_drilldown` reads the records behind a returned cluster. `accounting_insights_map_view` takes the canonical `{filters,renderer}` state and returns a safe view URL, with an absolute `dashboardUrl` for the connected deployment. Ask AI in Oatmilk knows the current filters, viewport and selected cluster and applies a requested view through its navigation tool. The server chooses the native Map address: `/insights?view=map` for company members and `/accountant/map?view=map` for outside accountants. Accountants see only sources their access permits, and event links open their existing year-end page. Company-member Ask AI does not open accountant portals; outside accountants can use Ask AI in their native Map and the same MCP tools, within their live client grants. `accounting_insights_map_export` returns an actual private PNG asset with a short-lived `downloadUrl` and an MCP resource link. It uses the same filters and viewport as the page. All map tools require `accounting:read` and enforce the person's current source permissions. They do not edit the books. Totals stay separated by currency, and coverage describes missing locations, unavailable layers and bounds or marker limits. These tools are in the `reports` toolset and work in clients without a map card; the Google map opens in Oatmilk. ## Events Clients that support MCP Events (ChatGPT, in Work chats) can be told when something happens: a receipt finishes reading (`receipt.processed`), an email reaches the company's Oatmilk inbox (`mail.received`), a deadline is near or overdue (`compliance.item.due_soon`, `compliance.item.overdue`), an invoice is paid, overdue or waiting for review (`invoice.paid`, `invoice.overdue`, `invoice.review_requested`), a contractor sends hours (`contractor.hours.submitted`) or a document is fully signed (`signing.envelope.completed`). Ask for it in plain words, such as "tell me when the Northwind invoice is paid". Each event is offered only when your role may read what it describes, carries ids and a link rather than content, and is signed with [Standard Webhooks](https://www.standardwebhooks.com/). The assistant reads the details with the usual tools before doing anything. ## The plugin The Oatmilk plugin adds the server along with guides that teach ChatGPT, Codex and Claude how Oatmilk works: getting started, receipts, bookkeeping, year-end, company details, contractor hours and notifications. Claude Code installs it from the [marketplace](https://app.getoatmilk.com/api/plugin/marketplace.json) with the commands above. For Codex, download the [plugin](https://app.getoatmilk.com/api/plugin/oatmilk.zip), unzip it, then run `codex plugin marketplace add ./oatmilk` and `codex plugin add oatmilk@oatmilk`. In the ChatGPT desktop app, list the unzipped folder in your personal marketplace (`~/.agents/plugins/marketplace.json`), restart the app and install Oatmilk from the Plugins Directory. ## Choose what the assistant sees The full server offers one tool for every action you're allowed to run, which is more than some clients can hold. Add `?toolset=` with one or more of these names to see only what you need: | Toolset | Includes | | --- | --- | | `autopilot` | What needs a person, Autopilot status, jobs, explanations, learned rules and settings, receipt reminders to cardholders, and the investigator. | | `transactions` | Entries, bank and card transactions, merchants and their profiles, trips and hotel holds, receipt investigations, reimbursements, categories, project tags, accounts, cards, reconciliation, Bank of Canada exchange rates, statement imports and the original statement files with their checked lines. | | `matching` | Receipt matching decisions, candidates and confirmation. | | `inbox` | Receipts, secure document requests, uploads of any file (intake), company mail, connected inboxes, evidence and processing jobs. | | `stripe` | Stripe activity, payouts, exceptions, tax confirmation and reports. | | `reports` | Reports, insights, a searchable world map with layers, drilldowns and image exports, software subscriptions, exports, tax preparation and the shareholder register. | | `compliance` | The compliance checklist, deadlines and reminders. | | `budgets` | Spending plans, tax and accountant obligations, designated reserve accounts, filing and payment dates, funding gaps and readiness alerts. | | `invoicing` | Invoices, customers and vendors, and payment methods. | | `documents` | Agreements, e-signatures and kept records such as filed tax returns, notices of assessment and company documents, with what company records say about the company for an administrator to check and save. | | `contractors` | For the company's finance team: the contractor directory, timesheets, payouts, and recruiting (job postings, candidates, interviews). | | `contractor` | For a contractor: only your own contractor_* tools (your hours and timesheets, pay periods, payouts and statements, agreements, profile and reminders). No accounting tools. | | `ai` | AI settings, classifier guidance, memory, the sandbox, the agents' live status, regulation updates from compliance research, the compliance portal (its library and search), and the Chief of Staff, the Oatmilk agent in Discord (its rules for each server and channel, people and roles, tools and scheduled posts). | | `connectors` | Wise, data connectors (Notion and Google Drive), webhooks and Notion. | | `history` | Everything anyone changed in the company, people, Ask AI, AI apps, the API and automation, with filters, the values before and after, and rolling changes back. | | `admin` | Organization settings and onboarding, exporting all of the company's data, members and team invitations, senders, API keys and their usage and request log, platform settings, notices about new people, experiments, runs and proposals. | ``` https://app.getoatmilk.com/api/mcp?toolset=inbox,transactions ``` ## Tools and actions Every tool is an API action under another name: `accounting_` followed by the action in snake case, so `uploads.inline` is `accounting_uploads_inline`. Contractor tools start with `contractor_`. Each action's page in the [API reference](https://app.getoatmilk.com/docs/api.md) names its tool. A few actions stay out of MCP on purpose, and their pages say why. Tools that delete, void or revoke something are marked as destructive, and tools that email people or call another service are marked as reaching outside Oatmilk, so a client can ask before running them. Pass `organizationId` to any tool to work in another company you belong to. ## What stays with people An assistant can prepare almost anything, but some steps always need the person in Oatmilk: approving a suggestion, signing an agreement, sending money, and seeing full bank or tax numbers. The tool then answers with the link to the exact page, and a good assistant hands it to you. ## Good prompts to start with - "What needs my attention in Oatmilk this week?" - "Which of my card purchases still need a receipt? Here are the receipts." - "Draft an invoice for Synthetic Ventures for 12 hours at $150, due in 30 days." - "Are any compliance deadlines coming up this month?"