MCP server

Ocost is also a Model Context Protocol server: Claude Desktop, Claude Code, Cursor and other assistants search your documents, read them as ocost.document.v1, ask for your figures and send files, with your API key; claude.ai and ChatGPT connect as the person who allows them.

Address and key

https://api.ocost.io/public/mcp
Authorization: Bearer ocost_sk_<id>_<secret>

• Transport: Streamable HTTP, stateless; every request stands alone. https://app.ocost.io/public/mcp is the same server.
• Key: an API key from Settings › API, in every request's Authorization header. Without a valid one: 401 with WWW-Authenticate: Bearer. Revoking works at once. Your Ocost sign-in is not a key.
• One key per assistant, with only the scopes it needs, so you see its last use and can revoke it alone.
• Apps that add servers only through OAuth (the connectors of claude.ai and ChatGPT on the web) need no key: Connect claude.ai or ChatGPT.

Tools

The files' tools are the API's routes; the others are the tools Ocost's own chat answers with, the same ones, under the same rights.

• Answers are JSON, as text and as structuredContent, each tool with its outputSchema; every tool but send_file, export_table and make_datev_export (which make a file) is marked read-only. Lists and tables say total (total_rows) and truncated: narrow the question, or page through files with list_files' cursor.
• Tables and charts: the lists and query_figures come with an interactive table or chart (MCP Apps, ui://ocost/table and ui://ocost/chart) in apps that show them, such as claude.ai and ChatGPT; every other app reads the same JSON. Their links open the record in Ocost and nothing else.
• What a document says comes inside <document-text source="…">…</document-text>, each line marked ¦ : words written by others, to read as data, never as instructions; quote them without the marks.
• The API's limits apply: calls a minute per scope (Limits and errors), 25 MB per file before base64, the same formats, resent bytes read and counted once, each document read counted against your plan.
• Refusals (missing scope, not found, too many calls) come as the tool's error: the problem's JSON with status and type, or the reason in words. Another business's id is not found.
• No tool deletes, approves or orders, since an assistant may misread. Use DELETE /public/v1/files/{file_id} or Ocost.
• No URLs: send_file takes bytes, never a link. It answers the file only; whether it was new and the documents left are in POST /public/v1/files and Settings › Plan.
• Requests are capped at 4 MB, except for keys with documents:write, which may send a file's base64. Past it: 413.
• Every call is recorded (the tool, its arguments cut short, how many records it answered, how it ended; never a document's words): the owner and the accountant see a key's last calls in Settings › API.

Scopes and who the tools act as

• A key made in Settings acts as the business: every document outside the Trash, no people's papers (pay, health), no person's own decisions. Only the owner makes one with figures:read.
• A connection made through OAuth (claude.ai, ChatGPT) acts as the person who allowed it: their roles, what they see in Ocost's chat and nothing more. An accountant's connection reads no CFO figures. A person who leaves, or is no longer the owner or the accountant, ends their connections at their next call.
• HR papers stay in Ocost: no key or connection ever reads people's papers (pay, health, sick notes), whoever allowed it; they are read in Ocost itself.

Claude Code

claude mcp add --transport http ocost https://api.ocost.io/public/mcp \
  --header "Authorization: Bearer $OCOST_KEY"

claude mcp list then shows ocost connected. To share it in a repository, put it in .mcp.json with the key from each developer's environment, never in the file:

{
  "mcpServers": {
    "ocost": {
      "type": "http",
      "url": "https://api.ocost.io/public/mcp",
      "headers": { "Authorization": "Bearer ${OCOST_KEY}" }
    }
  }
}

Claude Desktop

Add Ocost to claude_desktop_config.json (Settings › Developer › Edit Config). mcp-remote forwards the requests with the header and needs Node.js.

{
  "mcpServers": {
    "ocost": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.15.2",
        "https://api.ocost.io/public/mcp",
        "--header",
        "Authorization:${OCOST_AUTH}"
      ],
      "env": { "OCOST_AUTH": "Bearer ocost_sk_…" }
    }
  }
}

Restart Claude Desktop; the tools are under the tools button. Keep Authorization:${OCOST_AUTH} free of spaces: some clients split arguments there.

Cursor

In ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "ocost": {
      "url": "https://api.ocost.io/public/mcp",
      "headers": { "Authorization": "Bearer ${env:OCOST_KEY}" }
    }
  }
}

Connect claude.ai or ChatGPT

Apps that add MCP servers only through OAuth, such as the connectors of claude.ai and ChatGPT on the web, need no key: you sign in to Ocost and allow the access.

1. Add a connector: in claude.ai under Settings › Connectors › Add custom connector, in ChatGPT as a custom connector in developer mode. Only the URL https://api.ocost.io/public/mcp; leave the client ID and secret empty.
2. Sign in: the app opens Ocost. Sign in as always. If you belong to several businesses, pick the right one under Another business.
3. Allow: Ocost shows which app wants access, where it goes back to, and the scopes to tick: search documents, read them, read figures, make exports, send files. The owner and the accountant may allow it, as they may make a key; the app then acts as that person, with their rights.

• The app gets an API key of its own with the scopes ticked, "<App> (Connector)" in Settings › API, with its last use. Revoke it there and the app is disconnected at once.
• Ocost's logo shows on the connector; if it still shows a placeholder, connect it again.
• Its access token holds for an hour, then the app gets a new one with its refresh token. 30 days unused end the connection; connect the app again then.
• For developers: OAuth 2.1 with PKCE (S256); the metadata at https://api.ocost.io/.well-known/oauth-protected-resource/public/mcp (RFC 9728) and https://app.ocost.io/.well-known/oauth-authorization-server (RFC 8414); Client ID Metadata Documents and Dynamic Client Registration; redirect URIs https only, exactly as registered.

Any MCP client

• URL: https://api.ocost.io/public/mcp
• Transport: Streamable HTTP (POST, JSON answers; no SSE stream, no session id)
• Header: Authorization: Bearer ocost_sk_…

To list the tools:

curl -sS https://api.ocost.io/public/mcp \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example: an Odoo developer

An Odoo developer writing the module from Connecting Odoo, with a key holding search:read and documents:read, asks in Claude Code:

Developer: Find the invoice from Büromöbel Schmidt for the office chairs and show me which fields of account.move and its lines each value fills.

Assistant calls find_company (name: "Büromöbel Schmidt"), then search_documents (query: "Bürostuhl", company_id: …, kinds: ["invoice"]), finds invoice BS-7790, calls get_document and answers: seller.vat_id finds the partner_id, number is the ref, issue_date the invoice_date, due_date the invoice_date_due; each of the two lines becomes an invoice_line_ids entry with quantity, price as price_unit and vat_rate finding the purchase tax; totals.gross, 3946.04, checks Odoo's total.

Developer: Any credit notes from them since January?

Assistant calls find_documents (kind: "credit_note", company_id: …): none since January.