> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubic.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Connect your coding agent to cubic reviews, documentation, scans, billing, and team management.
cubic's MCP server lets your coding agent read review findings, look up codebase documentation,
request PR reviews, triage PR or codebase scan issues, and manage billing and team access.
You can use these tools directly from your agent. [Skills](/ide/skills) add workflows for tasks
such as fixing review comments. To review changes in your local checkout, use the
[cubic CLI](/ide/cli-review).
Sign in with your cubic account. Repository tools require a seat in the repository's organization
and read access to the repository on GitHub. Billing and team tools check your access to the
requested organization. Connecting MCP does not grant access to additional organizations or
repositories.
## Endpoint
Use this exact URL:
```text theme={null}
https://www.cubic.dev/api/mcp
```
Some MCP clients compare the protected resource URL exactly. Use `https://www.cubic.dev/api/mcp`,
not `https://cubic.dev/api/mcp`.
## Authentication
Use OAuth for new MCP connections. Your MCP client opens a browser, you approve cubic access, and the client stores and refreshes tokens.
OAuth is the recommended path and needs no `Authorization` header or API key in your configuration.
### Advanced: API key
For scripts, CI, or MCP clients that cannot complete an OAuth flow, you can use a personal API key instead. Open [Settings > API, CLI & MCP](https://www.cubic.dev/settings?tab=api-cli) and click **Generate API key** under **Personal API key**. The cubic CLI, the Members API and the Analytics API share this key, so if you already have one, use it: **Regenerate** replaces it everywhere. Keys start with `cbk_` and cubic only shows the full value once.
Send the key as a bearer token in the `Authorization` header and skip your client's OAuth login step:
```json theme={null}
{
"mcpServers": {
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp",
"headers": {
"Authorization": "Bearer cbk_..."
}
}
}
}
```
API keys are personal and grant the same access as the user who created them. Each team member should generate their own key, and you can revoke or regenerate it from the same settings page at any time. The same personal key also authenticates the [cubic CLI in CI and cloud agents](/ide/cli-review#run-in-ci-and-cloud-agents) and your [Members API](/account/members-api) and [Analytics API](/analytics/api) scripts, and regenerating it replaces the key for all of them.
## Install and log in
Cursor and VS Code support one-click MCP install links. For other clients, use the CLI or manual config steps below.
1. Click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D).
2. Confirm the install in Cursor.
3. Click **Connect** and complete OAuth.
Manual fallback:
Add cubic to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project.
If the file already has servers, add the `cubic` entry inside its `mcpServers` object:
```json theme={null}
{
"mcpServers": {
"cubic": {
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Open Cursor's MCP settings, connect cubic, and complete the browser sign-in flow.
If Cursor IDE is installed, first click [Add cubic to Cursor](https://cursor.com/en-US/install-mcp?name=cubic\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vd3d3LmN1YmljLmRldi9hcGkvbWNwIn0%3D). Cursor Agent reads the same MCP config.
Manual fallback:
Add cubic to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"cubic": {
"type": "http",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
```bash theme={null}
agent mcp enable cubic
agent mcp login cubic
agent mcp list-tools cubic
```
1. Click [Add cubic to VS Code](vscode:mcp/install?%7B%22name%22%3A%22cubic%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.cubic.dev%2Fapi%2Fmcp%22%7D).
2. Confirm the MCP install in VS Code.
3. Complete the OAuth prompt.
4. Run **MCP: List Servers** and confirm cubic is running.
Manual fallback:
1. Open the Command Palette.
2. Run **MCP: Add Server**.
3. Choose **HTTP**.
4. Enter `https://www.cubic.dev/api/mcp`.
5. Name it `cubic`.
6. Choose **Global** or **Workspace** for the configuration.
7. Run **MCP: List Servers**, start cubic, and complete OAuth when prompted.
Notion MCP connections are available on Notion Business and Enterprise plans. A workspace admin
must enable custom MCP servers before an agent can connect to cubic.
1. Ask a workspace admin to open **Settings** > **Connections** > **Manage** and turn on **Enable custom MCP servers**. If connections are restricted, the admin also needs to approve cubic's MCP URL.
2. Open your Custom Agent's **Settings**.
3. Go to **Tools & Access**.
4. Click **Add connection** > **Custom MCP server**.
5. Enter `https://www.cubic.dev/api/mcp`.
6. Name the connection `cubic`.
7. Connect with OAuth and complete the cubic sign-in flow.
8. Select which cubic tools the agent can use.
Read tools such as `list_wikis`, `get_wiki_page`, `list_scans`, and `get_pr_issues` can run
automatically if that matches your agent workflow.
See [Notion's MCP setup guide](https://www.notion.com/help/mcp-connections-for-custom-agents)
for workspace connection settings.
```bash theme={null}
claude mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Claude Code and run:
```text theme={null}
/mcp
```
Choose cubic and complete the browser OAuth flow.
Run `claude mcp list` in your terminal to check the connection.
Add the server, sign in through your browser, then list configured servers:
```bash theme={null}
codex mcp add cubic --url https://www.cubic.dev/api/mcp
codex mcp login cubic
codex mcp list
```
```bash theme={null}
gemini mcp add --transport http --scope user cubic https://www.cubic.dev/api/mcp
```
Open Gemini CLI and run:
```text theme={null}
/mcp auth cubic
/mcp
```
Add this to `~/.config/opencode/opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"cubic": {
"type": "remote",
"url": "https://www.cubic.dev/api/mcp",
"enabled": true
}
}
}
```
Then authenticate and verify:
```bash theme={null}
opencode mcp auth cubic
opencode mcp list
```
```bash theme={null}
droid mcp add cubic https://www.cubic.dev/api/mcp --type http
```
Open Droid, run `/mcp`, choose cubic, and complete the browser OAuth flow.
Install cubic's Pi target:
```bash theme={null}
npx @cubic-plugin/cubic-plugin install --to pi
```
The installer writes Pi's MCP config to `~/.config/mcp/mcp.json`.
Install the Pi MCP adapter if it is not already installed:
```bash theme={null}
pi install npm:pi-mcp-adapter
```
The adapter reads `~/.config/mcp/mcp.json` automatically. Confirm the config contains:
```json theme={null}
{
"mcpServers": {
"cubic": {
"auth": "oauth",
"url": "https://www.cubic.dev/api/mcp"
}
}
}
```
Open Pi and run:
```text theme={null}
/mcp-auth cubic
/mcp reconnect cubic
```
Use these details for any hosted MCP client that supports remote MCP OAuth and dynamic client
registration.
```text theme={null}
Transport: Streamable HTTP
URL: https://www.cubic.dev/api/mcp
Authentication: OAuth
```
Your client should open a browser for cubic consent, store the returned tokens, and send the
OAuth access token as a bearer token when calling the MCP endpoint.
## Try your first prompt
After connecting, ask your agent:
```text theme={null}
Use cubic to list the open review issues on https://github.com/OWNER/REPO/pull/NUMBER.
```
Replace the URL with a PR you can access. The agent should call `get_pr_issues` and show the
open findings with their file locations, severity, and descriptions. The result also reports
the state of cubic's latest review of the PR and whether the PR has commits cubic hasn't
reviewed yet. An empty list means the current commit has no open findings only when the latest
review completed and no newer commits exist. `get_pr_issues` doesn't start a review.
For workflows that also investigate and fix the findings, [install cubic's skills](/ide/skills).
## Available tools
| Tool | Description |
| :- | :- |
| `get_pr_issues` | List open cubic PR review issues and the state of the PR's latest review |
| `trigger_pr_review` | Start a full PR review; an already queued or running review continues without restarting |
| `update_pr_issue_status` | Resolve, reopen, or dismiss a PR issue on its GitHub review thread and queue an attributed reply |
| `set_pr_auto_fix` | Turn [auto-fix](/ai-review/auto-fix) on or off for a pull request |
| `list_wikis` | List the wikis you have access to, one page at a time |
| `list_wiki_pages` | List all available wiki pages for a repository |
| `get_wiki_page` | Retrieve the content of a specific wiki page |
| `list_scans` | List repository scan summaries |
| `get_scan` | List aggregated scan issues with filters and pagination |
| `resolve_github_user_contacts` | Resolve GitHub usernames to email and Slack mentions |
| `get_issue` | Get full details and code context for a codebase scan issue |
| `update_issue_status` | Update a codebase scan issue's triage status, with optional feedback for future scans |
| `list_learnings` | List AI review learnings for a repository, one page at a time |
| `get_learning` | Get full details of a specific learning |
| `list_organizations` | List accessible organizations and your billing and team-management permissions |
| `get_subscription` | Get the current plan, purchased and assigned seats, review usage, and pending changes |
| `list_members` | List organization members with their GitHub user IDs, work emails, roles, and seats |
| `update_member_seat` | Enable or disable an existing member's seat, change their role, or both |
| `update_subscription` | Increase purchased seats or upgrade Team to Pro |
| `update_flex_capacity` | Enable or disable automatic flex purchases and set a spending cap |
Use issue IDs from `get_pr_issues` with `update_pr_issue_status`. For codebase scans, use IDs
from `get_scan` with `get_issue` or `update_issue_status`.
The two update tools change issue state. `update_pr_issue_status` also changes the GitHub
review thread and posts its reply asynchronously. `trigger_pr_review` starts a cloud review.
The PR tools accept a GitHub or cubic PR URL, `owner/repository#number`, or the repository
with the PR's number, head branch, or head commit SHA. `list_wikis` and `list_learnings` return
one page at a time and say when more results exist.
Each tool has a display title and hints that say whether it only reads data or makes changes.
Clients may use these hints, for example to run read-only tools without asking you. Whether your
client asks before a tool that makes changes depends on the client and its settings. When your
client connects, cubic also sends instructions that explain how the tools work together, such as
fixing a PR's findings and then recording each outcome with `update_pr_issue_status`.
Results that quote code or text other people wrote, such as PR findings, wiki pages, scan
reports, and learnings, wrap that text in tags that mark it as data. The server instructions
tell your agent not to follow instructions inside those tags.
## Billing and team management
Start with `list_organizations` and use the returned GitHub organization login in the
`organization` argument. Each organization also has a `githubAccountId`, which stays the same when
the organization is renamed. Use `get_subscription` to check purchased capacity and pending
changes, and `list_members` to find a member's GitHub user ID, current role, and seat.
`list_members` accepts `search`, plus `role` and `seat` filters. Each member includes
`workEmail`, the member's work email for that organization, or `null` when cubic has none.
Organization and member lists return one page at a time. Pass the returned `nextCursor` to get
the next page.
### Permissions and supported subscriptions
Your MCP client uses your cubic permissions. Reading billing and member information requires
organization access. Changing subscriptions, seats, or roles requires an organization admin;
cubic checks current permissions on every mutation. Admins retain billing access when their
own review seat is disabled.
MCP mutations require an active paid Stripe subscription. Free customers receive a link to
upgrade in cubic. Vercel customers must make changes through the cubic UI or Vercel Marketplace.
Reads remain available subject to organization access.
### Assign seats and change roles
`update_member_seat` uses existing purchased capacity and never buys seats. Supply the member's
`githubUserId` from `list_members`, plus either or both of these pairs:
* `seat` and `expectedSeat`: the desired seat state and the current `seat` value.
* `role` and `expectedRole`: the desired and current role, each one of `admin`, `member`, or `viewer`.
Combined seat and role changes either both apply or neither applies. If the member's state
has changed, refresh `list_members` before submitting another change. Repeating a change that
already matches the desired state returns a no-op.
Admins cannot remove their own admin role or disable the last active human admin. Bots cannot
be admins. If no purchased seats are available, increase capacity with `update_subscription`
before enabling another billable member.
### Buy seats or upgrade the plan
`update_subscription` accepts `seats`, `plan: "pro"`, or both, plus an `idempotencyKey` for the
purchase. `seats` is the desired total, not the number to add: to go from 5 seats to 8, pass
`seats: 8`. The billing interval stays the same. Upgrades to Pro, and seat increases on Pro or Max,
must meet the organization's minimum seat requirement; an error tells you the required count.
A subscription can cover multiple organizations through a shared billing account. Purchases
apply to that subscription; the result reports the number of affected organizations.
Use the cubic UI for upgrades to Max, seat reductions, downgrades, billing-interval changes, or
subscriptions with an existing scheduled, pending, or cancellation change.
### Payments and retries
Check the returned status before treating a purchase as complete:
| Status | Meaning |
| :- | :- |
| `applied` | Stripe has applied the requested subscription change |
| `no_change` | The subscription already matches the requested state |
| `payment_action_required` | Complete payment using the returned action link; the requested capacity is not yet available |
| `processing` | The outcome is uncertain; check the subscription and the returned action before making another purchase |
For a retry, reuse the same `idempotencyKey` with identical arguments. After a timeout, check
`get_subscription` before proceeding; do not generate a fresh key merely because the response
was lost. Retry deduplication follows Stripe's key-retention limits. Reusing a retained key
with different purchase parameters can be rejected.
## Common prompts
* "Show open cubic review issues on PR #42 in acme/backend"
* "Start a cubic review of PR #42 in acme/backend"
* "List wiki pages for acme/backend"
* "Show me the authentication system wiki page"
* "List codebase scan issues in acme/backend with severity at least 7"
* "Mark scan issue abc as false positive with feedback"
* "What review learnings apply to this repository?"
* "How many purchased and available seats does acme have?"
* "Enable Alice's review seat in acme using our available capacity"
* "Make Alice an admin in acme"
* "Increase acme's total purchased seats from 5 to 8"
* "Upgrade acme from Team to Pro with 8 seats"
## Troubleshooting
Confirm your configured URL is exactly `https://www.cubic.dev/api/mcp`. Replacing `www.cubic.dev`
with `cubic.dev` can cause OAuth clients to reject the connection.
cubic answers an expired or revoked token with a 401 response. Its `WWW-Authenticate` header
carries `error="invalid_token"`, the signal many OAuth clients wait for before they refresh the
token. If your client doesn't recover, run its login command again and complete the browser
flow. If you use an API key, check that it hasn't been revoked or regenerated.
Restart your AI client after updating configuration. For Cursor Agent, make sure the server is in
`~/.cursor/mcp.json` or project `.cursor/mcp.json`, not only Cursor's `settings.json`.
Confirm the repository has an [AI Wiki generated](/wiki/ai-wiki), verify you can read the
repository on GitHub, and check that `owner` and `repo` match GitHub exactly.
cubic syncs repository access from GitHub. Access you gain or lose through a GitHub team reaches
cubic with the daily sync, so it can take up to a day to apply to MCP tools. If you were recently
given access to the repository, open its wiki page in the cubic web app once, then retry the tool.
MCP provides cloud findings and context. Install and sign in to the [cubic CLI](/ide/cli-review)
to run a local review. If you want to start it from your agent, also [install the skills](/ide/skills).
### Automatic flex capacity
`get_subscription` includes flex availability, spending settings, configured purchase size and price, and paid/pending usage. `list_organizations` reports `canUpdateFlexCapacity`; mutations still check current permissions and billing eligibility.
Use `update_flex_capacity` with `organization` and at least one of `enabled` or `spendingLimitCents`. The cap is an **absolute USD-cent amount per quota period**, not an increment or a charge amount; it carries forward into future periods. Omitting a field preserves it. For example, `spendingLimitCents: 10000` sets a \$100 cap. Changing the cap alone does not enable flex.
An organization admin can enable flex on an eligible active paid Stripe subscription. Free, trial, and Vercel customers must use the UI. Disable-only requests remain available after a Stripe billing lapse and preserve the saved cap. Any request that edits the cap requires an active paid subscription, including requests that also disable flex. This version does not change purchase size or remove a cap. Flex has no cap by default, so enabling it with none saved allows unlimited spending; set `spendingLimitCents` when the user wants a limit.
Flex and automatic seat purchases can both be enabled. Changing one setting preserves the other. Saving settings does not initiate a charge, but ongoing or subsequent review processing can purchase capacity automatically. Obtain an explicit user instruction before enabling flex or increasing its cap. The result reports `applied` or `no_change` for settings, not a completed purchase. Disabling or lowering the cap does not cancel existing invoices, refund spending, or stop in-flight purchases. Pending invoices consume budget but grant no capacity until paid. Retry blocked reviews separately.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.