MCP Interface

MCP (Model Context Protocol) is an open protocol that lets AI coding tools request context from external sources. Superpositional exposes an MCP server that your coding tools connect to directly. When your AI agent needs to understand your codebase, review a plan, or diagnose an error, it queries Superpositional through MCP and gets back structured, codebase-grounded responses.

This is the same indexed system graph that powers the Chat page, delivered directly to your AI coding tool.

MCP endpoint

Your organisation's MCP endpoint is:

https://mcp.superpositional.io

Authentication uses OAuth. When you first connect a tool, it opens a browser window for you to sign in with your Superpositional account (Google or GitHub). After authentication, the tool stores the token and reconnects automatically.

Connecting your tools

Cursor

Add the following to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "superpositional": {
      "url": "https://mcp.superpositional.io"
    }
  }
}

Restart Cursor. On first use, Cursor opens a browser window for OAuth authentication.

VS Code (Copilot)

Add the following to your VS Code MCP settings (.vscode/mcp.json):

{
  "servers": {
    "superpositional": {
      "url": "https://mcp.superpositional.io"
    }
  }
}

Reload VS Code. The MCP client handles the OAuth flow automatically.

Kiro

Add the following to your Kiro MCP configuration (.kiro/settings/mcp.json or ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "superpositional": {
      "url": "https://mcp.superpositional.io"
    }
  }
}

Save and reload. Kiro handles the OAuth flow automatically.

Windsurf

Add the MCP server in Windsurf's MCP settings with the endpoint URL https://mcp.superpositional.io. Windsurf handles the OAuth flow on first connection.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "superpositional": {
      "url": "https://mcp.superpositional.io"
    }
  }
}

Restart Claude Desktop. It opens a browser window for OAuth on first use.

Available tools

The MCP server exposes build-time intelligence tools that give your AI agent system-level insight it can't get from reading files or running grep. Your agent discovers and uses these automatically — you don't need to call them directly.

The tools fall into three categories: understanding your system, reviewing your work, and managing configuration.

ask

What it does: Answers natural-language questions about a repository using the indexed system graph. Returns a synthesised answer with source references (file paths, line numbers, relevant code).

When to use it: When you need to understand how something works, find where logic lives, or get oriented in unfamiliar code. The answer is grounded in real code — not generic advice.

Example prompts:

• "How does the authentication flow work?"
• "What modules depend on the database connection pool?"
• "Where is the retry logic for failed API calls?"

What makes it different from grep: Semantic understanding. Asking "where is error handling for payments?" finds the relevant code even if it doesn't contain those exact words. Answers include file:line references so you can verify.

Requires: An indexed repository.

review_plan

What it does: Takes a natural-language description of what you intend to build and checks it against the system's architecture guards and code graph. Returns feedback on potential issues — boundary violations, dependency concerns, conflicts with existing patterns.

When to use it: Before writing code. Describe your approach and get feedback on whether it fits the existing architecture. Most valuable for work that crosses module boundaries, introduces new patterns, or touches shared infrastructure.

Example prompts:

• "I'm going to add caching to the user service using a Redis sidecar. Review this plan."
• "Plan: extract the validation logic into a shared library that both API and worker consume."
• "I want to add WebSocket support to the notification service for real-time updates."

What you get back: Guard-based feedback identifying architectural concerns, pattern conflicts, or dependency issues with your proposed approach. If the plan looks sound, you get confirmation.

Works without a repo: Yes — you get principle-based feedback only (no codebase-specific analysis).

review_diff

What it does: Runs a code diff through the full review pipeline — the same analysis that runs on pull requests. This includes architecture guards, structural analysis, and (for larger diffs) lens-based evaluation covering architecture integrity, dependency impact, test strategy, and change quality.

When to use it: After writing code, before pushing. Pass your git diff and get the same quality of review you'd get on a PR, but faster and earlier. Also useful as an automated check during multi-step implementations (see workflow tips).

What you get back: An assessment with findings, affected entities, guard verdicts, and a summary verdict (approve / concerns / reject). Findings reference specific lines in your diff.

Depth scales with diff size:

• Small, focused changes get a quick guard-only pass.
• Medium changes get targeted retrieval (fetching definitions of symbols you touched) plus guards.
• Large or complex changes get the full pipeline including architectural lenses.

Works without a repo: Yes — you get guard-based review only (no codebase-specific context).

review_spec

What it does: Reviews a spec or design document against the system's architecture and coding standards. Checks whether the proposed design is sound, identifies gaps, and flags conflicts with existing system structure.

When to use it: When you've written a requirements document, design doc, or task list and want architectural feedback before starting implementation. Catches structural issues in the design phase — cheaper to fix than after the code is written.

What you get back: Structured findings with severity levels, categorised by type (architecture, testing, security, quality). Each finding is grounded in specific concerns about the spec content.

Works without a repo: Yes — you get principle-based review only (no codebase-specific alignment checking).

review_issue

What it does: Analyses a bug report or feature request against your codebase. Finds relevant code, traces potential causes, identifies what areas of the system are involved, and suggests investigation approaches.

When to use it: When picking up an issue and you want to understand the codebase context before diving in. Particularly useful for issues in unfamiliar areas of the code.

What you get back: Codebase-grounded analysis with source references — what code is likely involved, what the potential causes are, and where to look.

Works without a repo: Yes — you get general analysis without codebase specifics.

get_blast_radius

What it does: Given a list of file paths (or a commit SHA), computes what's affected by those changes. Returns directly affected entities and their transitive dependents — callers, importers, subclasses, implementors — up to a configurable depth.

When to use it: Before making changes, to understand impact. "If I modify these files, what else in the system is affected?" The output is structured data (entity lists with relationships), not prose — designed for agents to reason over programmatically.

What makes it different from ask: This is a deterministic graph traversal, not an LLM-synthesised answer. It returns the complete dependency fan-out, not a summary. Fast (sub-second), cheap (no LLM call), and structurally complete.

Example uses:

• Deciding whether a refactoring is safe
• Identifying what tests to run after a change
• Understanding whether a change is contained to one module or crosses boundaries

Requires: An indexed repository.

system_context

What it does: Returns holistic context for a code entity — its role in the system, what it depends on, what depends on it, architectural signals, and what the implications of changing it are.

When to use it: Before modifying a function, class, or module. It's the "look before you leap" tool — quick orientation on what you're about to affect. Runs in under 5 seconds with no evaluator loop.

What makes it different from ask: Faster (deterministic planner, no full LLM synthesis), structured output (role, dependencies, dependents, signals), and focused on a specific entity rather than an open-ended question. Think of it as hovering over a symbol to see its full context.

Requires: An indexed repository.

diagnose

What it does: Takes a fault description — an error message, stack trace, or description of unexpected behaviour — and performs root cause analysis against the code graph. Traces through dependencies, change history, and architectural context to identify the cause, not just the symptom.

When to use it: When you hit an error during development, a test fails unexpectedly, or you're investigating a production issue. Pass the error details and get analysis that goes beyond the stack trace.

Example prompts:

• "Diagnose: ConnectionRefusedError when calling the payment service from the order handler"
• "Why is this test failing? Expected 3 items but got 0 in test_user_notifications"
• Paste a full stack trace

What you get back: Root cause analysis with source references, relevant code paths, and suggestions for resolution. The analysis uses the code graph to trace causality — what feeds into the failing code, what changed recently, what's connected.

Works without a repo: Yes — you get generic fault reasoning without code graph context.

list_repos

What it does: Lists all indexed repositories in your org with their name, status, last indexed timestamp, file count, entity count, and descriptions. Also returns navigational anchors — key entry points into each repo's codebase.

When to use it: To discover what's available, check indexing status, or find the right repo name to pass to other tools. The anchors help your agent orient quickly in a new repo.

list_guards

What it does: Lists all guard definitions with their enabled/disabled status and principles. Guards are the coding standards that review_diff and review_plan enforce.

When to use it: To see what standards are being enforced, understand what a guard checks, or decide whether to adjust your org's guard configuration.

list_rules

What it does: Lists compiled rules for a specific repository — the custom rules that have been defined for that codebase, with their category, review guidance, and diagnostic guidance.

When to use it: To understand what repo-specific rules apply beyond the standard guards. Rules are more granular and codebase-specific than guards.

Requires: An indexed repository.

list_signals

What it does: Lists active signals — the system's ongoing risk assessments for your repositories. Signals represent patterns, trends, or risks that Superpositional has identified and is tracking over time. They include severity, trajectory (improving/worsening/stable), and evidence.

When to use it: To find what needs attention. Signals surface risks that are growing, architectural concerns that span multiple PRs, test gaps, and quality issues. Useful for deciding what to work on next or checking whether recent changes introduced new concerns.

Filtering options: By disposition (active, resolved, dismissed) or by repository.

How it works

After connecting, your AI tool queries Superpositional in the background when it needs codebase context. You don't need to trigger it manually — the tool decides when to use MCP based on the task.

All tools are scoped to your organisation. The MCP server only returns data from repositories your org has indexed. The connection is read-only from your tool's perspective — it pulls context from Superpositional, it doesn't push your editor state anywhere.

For practical patterns on combining these tools in your workflow, see MCP Workflow Tips.

Troubleshooting

If your AI tool isn't picking up context from Superpositional:

• Check the endpoint URL. It should be exactly https://mcp.superpositional.io.
• Re-authenticate. If your OAuth token has expired, the tool should prompt you to sign in again. If it doesn't, remove the MCP server configuration and re-add it.
• Verify your repos are indexed. MCP can only serve context for repositories that have been indexed. Check the Repos page in the app.
• Check your network. The MCP endpoint requires HTTPS access to mcp.superpositional.io. If you're behind a corporate proxy, ensure this domain is allowed.