The Company-Brain MCP

What the Company-Brain MCP is

The Company-Brain MCP is a first-party Model Context Protocol server built directly into the CompanyOS API. Connect an MCP client — Claude Code, Claude Desktop, or anything that speaks MCP — and it can read and write everything you can reach in CompanyOS: projects, tasks, boards, comments, notifications, meetings, notes, calendar, teams, the org and its members, activity, the knowledge brain, and the AI agents. Every tool call is scoped to one organization and runs with your permissions, so an agent can do exactly what you can do in the web app — nothing more.

How access works

The MCP uses standard OAuth 2.1 so you never hand a client a raw API key. The first time a client connects it discovers the authorization server, registers itself, and opens a CompanyOS consent screen in your browser. You pick a workspace and approve a set of permissions; the client receives a token scoped to that org and those permissions.

• OAuth 2.1 + Dynamic Client Registration (RFC 7591) — clients self-register, no manual app setup.
• PKCE (S256) on the authorization code flow — safe for public/native clients.
• RFC 9728 protected-resource metadata — clients auto-discover the auth server from the MCP endpoint.
• Per-organization or all-organization tokens — mint a token for one workspace, or choose *All my organizations* to receive a single cross-org token that works in every workspace you belong to.
• `org_id` targeting — with an all-organization token, every tool accepts an optional org_id so the agent chooses which workspace a call lands in; a single-org token infers it automatically.
• Granular scopes — you approve exactly which domains the agent may read and write.

The consent screen

When a client connects you land on the CompanyOS authorization page. Choose a single workspace, or pick All my organizations to authorize every workspace you belong to at once with one cross-org token, then tick the permissions. Read permissions for the core domains are pre-checked as a sensible baseline; write and elevated permissions are an explicit, deliberate opt-in. Approve to connect, or decline to cancel — either way you are returned to the client.

Root / Admin — full access

Install

Claude Code

Add the server, then run /mcp and complete the browser consent:

claude mcp add --transport http companyos https://api.company.chele.bi/api/v1/mcp

# then, inside Claude Code:
/mcp        # opens the CompanyOS consent screen in your browser

Claude Desktop and other clients

Point any MCP client at the endpoint. Clients that don't yet speak OAuth-protected HTTP natively can bridge through mcp-remote:

{
  "mcpServers": {
    "companyos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.company.chele.bi/api/v1/mcp"]
    }
  }
}

Permissions (scopes)

Scopes are grouped by domain, with a read tier, a write tier, and a few elevated tiers for sensitive admin actions. Approving a domain's read scope lets the agent see that data; the write scope lets it create, edit, and delete. Root/Admin grants all of them at once.

What the agent can do (tool catalog)

The MCP exposes the full member surface — every action a person can take in the web app, an agent can take through a tool. Tools are grouped below by domain. Creates accept an optional idempotency_key so a retried call never duplicates work, and destructive deletes take a confirm flag (call once to preview, again with confirm=true to apply).

Tasks and boards

Labels (tags)

Triage

Projects

Comments

Notifications

Teams

Organization, members and invites

Meetings

Meeting templates and recipes

Notes

Calendar

Activity

Company brain

AI agents and keys

Views, vocabulary and workflow

Automation

Integrations and profile

Safety and conventions

• Org-scoped — every token is pinned to one organization; tools only ever touch that workspace.
• Scope-checked per call — a tool runs only if your token carries its scope, otherwise it returns insufficient_scope.
• Idempotent creates — pass an idempotency_key and a retried create returns the original result instead of duplicating.
• Confirm-gated deletes — destructive tools preview first and only act when called again with confirm=true.
• Mirrors the app — every action is exactly what a member can do in the UI, and shows up in activity the same way.