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 Elliptic API. It exposes your workspace as a set of callable tools, so an MCP client like Claude Code, Cursor, or Claude Desktop can read and write the same surfaces you use in the app: tasks and boards, projects, notes, meetings and transcripts, calendar, comments, notifications, teams, the org and its members, the activity feed, the brain, and your AI agents. This is the mechanism that makes Elliptic Jira for your agents. An agent connects as a member and operates the same surfaces you do, on the org's own model key.

The server is a stateless FastMCP app mounted in the API at /api/v1/mcp. Each tool runs through a single boundary that authenticates the caller, enforces the tool's required scope, resolves the org context, and owns the database transaction, committing on success and rolling back on error. Every call is scoped to one organization and acts as the connecting user, so a tool can do exactly what that person can do in the web app, no more. Whatever an agent does through the MCP lands in activity the same way a person's action would.

Authenticating

The MCP is protected by 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 Elliptic consent screen in your browser. You pick a workspace and approve a set of permissions, and the client receives a token scoped to that org and those permissions. From then on the client refreshes silently.

• Dynamic client registration (RFC 7591). Clients self-register at the registration endpoint as public PKCE clients. There is no manual app setup, and each registered client gets a generated client_id.
• PKCE with S256. The authorization-code flow requires a code_challenge using the S256 method. Other methods and a missing challenge are rejected, which keeps the flow safe for public and native clients.
• Canonical resource binding. A resource parameter (RFC 8707) on the authorize and token requests must equal the canonical MCP resource URI, so a code minted for this server cannot be replayed against another audience. Clients that omit resource still work: the server binds the request to the canonical URI from its own metadata.
• Short-lived codes, rotating refresh. Authorization codes are single-use and expire after 60 seconds. Refresh tokens rotate on every use, and reusing a consumed refresh token revokes the whole token family.
• Signed request envelope. The validated authorize parameters are signed into a request id that the consent page cannot tamper with. It is valid for 10 minutes.

The consent screen

When a client connects you land on the Elliptic authorization page. You choose a single workspace, or pick all your organizations, then approve the permissions the client asked for. The screen groups permissions by domain. Every domain's read scope is the baseline set: it shows as Always on and stays checked and locked, so the standard read surface is always granted. 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.

Consent is the only place permissions are decided. The token the client receives carries exactly the scopes you ticked. A client that requested specific scopes caps the grant at its request; a client that requested none (most MCP clients) receives precisely your selection. Nothing the client does later can widen the grant without a fresh consent.

Personal access tokens (the no-OAuth path)

If you would rather not run the OAuth flow, the MCP also accepts a Elliptic personal access token directly. Send your cos_pat_ token as a Bearer header (or as an x-api-key header) and the call is authenticated as you. A PAT is treated like a logged-in session: it acts across every organization you belong to and carries the full scope set, so use it only with clients you trust. OAuth with hand-picked scopes is the safer default for third-party agents.

Single-org versus all-orgs tokens

Your token comes in one of two shapes, decided at consent time.

• Pinned single-org token. You picked one workspace, so the token is bound to that org. Tools target it automatically, and if a call passes an org_id that does not match, it is rejected. This is the tightest setup: the agent can only ever touch the one workspace you chose.
• Cross-org token (all organizations). You picked all your organizations, so the token carries no fixed org. Every org-scoped tool then accepts an optional org_id to choose which workspace the call lands in. If you omit it, the call falls back to your earliest-joined org, so always pass org_id when you mean a specific one.

Discovery

Clients configure themselves from the endpoint alone, with no hand-entered URLs beyond the MCP address. Two mechanisms make that work.

First, an unauthenticated request to the MCP endpoint returns a 401 with an RFC 9728 Bearer challenge. The WWW-Authenticate header points at the protected-resource metadata, so a client that hits the endpoint cold immediately learns where to begin the OAuth flow:

WWW-Authenticate: Bearer resource_metadata="https://api.elliptic.sh/.well-known/oauth-protected-resource/api/v1/mcp"

Second, the well-known documents let the client finish self-configuring:

Installing

Claude Code

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

claude mcp add --transport http elliptic https://api.elliptic.sh/api/v1/mcp

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

Cursor

Cursor speaks MCP natively. Add Elliptic to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), then open Cursor Settings, MCP, and complete the browser consent on first use:

{
  "mcpServers": {
    "elliptic": {
      "url": "https://api.elliptic.sh/api/v1/mcp"
    }
  }
}

The first tool call opens the same Elliptic OAuth consent in your browser. No API key is stored in the file.

Claude Desktop and other clients

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

{
  "mcpServers": {
    "elliptic": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.elliptic.sh/api/v1/mcp"]
    }
  }
}

The scope catalog

Permissions are expressed as scopes, grouped by domain. Most domains have a read scope and a write scope: approving the read scope lets the agent see that data, and the write scope lets it create, edit, and delete. The read scope of every domain is the baseline set, so it is always on at consent and cannot be unchecked, which means the standard read surface is granted by default. A handful of scopes are flagged Elevated and stay unchecked until you opt in deliberately. The Root / Admin toggle selects everything at once.

The elevated scopes, the ones that stay unchecked until you opt in, are agents:write, agents:keys, org:manage, org:create, integrations:manage, sources:manage, and orgs:all. Note that there is no separate delete scope: deleting an event uses events:write, deleting a note uses notes:write, and so on. Write is enough to remove what write can create.

The tool catalog

The MCP exposes 144 tools, grouped below by domain. This is most of the member surface, but it is not literal parity with every screen. There are no MCP tools for connected sources or GitHub linking, and there are no cycle, milestone, or PQL-style query tools. Read tools list and fetch, write tools create, edit, move, and delete. Two cross-cutting conventions apply throughout: many creates accept an optional idempotency_key so a retried call never duplicates work, and the most destructive deletes take a confirm flag (call once with confirm=false to preview, again with confirm=true to apply).

Tasks, boards, labels, and triage

Projects

Meetings

Notes, calendar, comments, and notifications

Organization, teams, members, and invites

Activity and the brain

The brain tools are the agent-facing side of the company brain: they exist so an agent can orient itself before it acts, catching up on what changed, finding open threads, and resuming a project without you spelling out the state each time. They are read-only and run under brain:read.

AI agents and keys

Views, vocabulary, workflow, and automation

Integrations and profile

Managing access

Every consent you give creates a connected-app grant tied to your account, the client, and the org (or, for a cross-org token, no specific org). You can see and revoke these at any time.

• Connected apps (grants). Each connected client shows up as a grant with its name, the org it covers (or all your organizations), its scopes, its status, and when it was granted. Re-approving the same client updates the existing grant rather than stacking duplicates.
• Revoking a grant. Revoking a grant kills the whole token family behind it, every access and refresh token, so the client loses access immediately and must re-consent to reconnect.
• Token revocation (RFC 7009). A client can also revoke its own token at the revocation endpoint. Revoking any token in a family tears down the family, and unknown tokens are a safe no-op.

Confidential bot apps (client_credentials)

For an unattended bot that has no browser to consent through, register a confidential OAuth app. You get a client_id and a one-time client_secret (shown once at creation, stored only as a hash). The app then exchanges those credentials at the token endpoint with grant_type=client_credentials and receives a bot token that acts as you, the owner, across your organizations. Revoking the app deactivates it and stops it from minting new tokens.

Conventions

A few rules hold across every tool, so agents behave predictably and safely.

• Org-scoped, acting as you. Every tool resolves to one organization and runs with your membership and role. It can do exactly what you can do in the app, and the result appears in activity the same way.
• Per-call scope checks. A tool runs only if your token carries its required scope. If not, it returns insufficient_scope and does nothing. Scopes are checked on every single call, not just at connect time.
• Idempotent creates. Pass an idempotency_key on a supported create and a retried call returns the original result instead of duplicating work, which makes agent retries safe.
• Confirm-gated deletes. The most destructive tools take a confirm flag. Call once with confirm=false to preview what would be removed, then again with confirm=true to apply it.
• Live membership re-checks. With a cross-org token, your membership of the target org is verified on every call, so losing access to an org takes effect instantly.