> ## 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 access to the repository's installation.
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.
Existing cubic API keys are still accepted. For new connections, use OAuth without adding an
`Authorization` header or API key to your configuration.
## 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. An empty result means
there are no open cubic findings on that PR; it does not trigger a new 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, excluding resolved or addressed findings |
| `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 |
| `list_wikis` | List all wikis you have access to |
| `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 |
| `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, their roles, and seat assignments |
| `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.
## Billing and team management
Start with `list_organizations` and use the returned GitHub organization login in the
`organization` argument. Use `get_subscription` to check purchased capacity and pending changes,
and `list_members` to find a member's ID and current role and seat state. Member lists support
search; organization and member lists support pagination using the returned `nextCursor`.
### 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 `memberId`
from `list_members`, plus either or both of these pairs:
* `enabled` and `expectedEnabled`: the desired seat state and the current `seatEnabled` 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. Pro upgrades 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 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.
Run your client's login command again and complete the browser flow. If you still use a legacy
API-key config, migrate it to OAuth.
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 have access to the
repository's installation, and check that `owner` and `repo` match GitHub exactly.
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 support unlimited spending.
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.