Connect an assistant

Ocost is also a Model Context Protocol (MCP) server. Connect Claude Desktop, Claude Code, Cursor or another assistant, and it searches your documents, reads them, asks for your figures and sends files. claude.ai and ChatGPT connect through OAuth instead of a key.

The server

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

The server speaks Streamable HTTP and keeps no session, so every request stands alone. https://app.ocost.io/public/mcp is the same server. Give each assistant its own key with only the scopes it needs. Then you see its last use in Settings › API and can revoke it alone. MCP tools lists every tool with its scope and arguments.

Claude Code

Add the server with your key from the environment:

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

claude mcp list then shows ocost as connected. To share the server in a repository, put it in .mcp.json. Keep the key in 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

Open Settings › Developer › Edit Config and add Ocost to claude_desktop_config.json. mcp-remote forwards the requests with your header, and it 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, and the tools show under the tools button. Keep Authorization:${OCOST_AUTH} free of spaces, because some clients split arguments there.

Cursor

Add Ocost to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

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

claude.ai and ChatGPT

These apps add servers only through OAuth. You need no key: you sign in to Ocost and allow the access.

1. Add a custom connector. In claude.ai, open Settings › Connectors › Add custom connector. In ChatGPT, add a custom connector in developer mode.
2. Enter only the URL https://api.ocost.io/public/mcp. Leave the client ID and secret empty.
3. Sign in to Ocost when the app opens it. If you belong to several businesses, pick one under Another business.
4. Tick the scopes to allow and confirm. Only the owner and the accountant may allow access.

The app then acts as you, with your rights. It gets a key of its own, listed as "<App> (Connector)" in Settings › API. Revoke that key to disconnect the app at once. The app renews its access token every hour by itself. After 30 days unused, the connection ends and you connect the app again.

Building an OAuth client yourself? Ocost uses OAuth 2.1 with PKCE (S256). The metadata is 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). Ocost takes Client ID Metadata Documents and Dynamic Client Registration. Redirect URIs must use https and match exactly.

Any other client

Point it at the URL with the Authorization header. The server answers POST requests with JSON, without an SSE stream or session id. List the tools to check the connection:

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"}'

Without a valid key, the server answers 401 with WWW-Authenticate: Bearer. Your Ocost sign-in is not a key.

What the tools may do

A key made in Settings acts as the business. It reads every document outside the Trash, but no person's own decisions. Only the owner makes a key with figures:read. An OAuth connection acts as the person who allowed it and sees what they see in Ocost's chat. No key or connection ever reads people's papers, such as pay slips or sick notes.

No tool deletes, approves or orders anything. The API's limits apply to every tool call.

Words read from a document arrive inside <document-text>, each line marked ¦ . They are data written by others, never instructions. In claude.ai and ChatGPT, lists and figures also come as an interactive table or chart.

Every call is recorded, without a document's words. The owner and the accountant see a key's last calls in Settings › API.