Installing MCP

Connect your AI coding tools to Superpositional via MCP so your agent gets live system context while you code.

MCP (Model Context Protocol) is how your AI coding tools talk to Superpositional. Once connected, your agent can query the system graph — architecture, dependencies, blast radius, plan review — directly from your editor.

This is the fastest way to get value from Superpositional. Once your repos are indexed, MCP gives your agent structured context about your codebase without switching to the browser.

What you need first

A Superpositional account (sign up here)
At least one indexed repository (add repos here)
An MCP-capable AI coding tool (Cursor, VS Code, Kiro, Windsurf, Claude Desktop)

MCP endpoint

Your organisation's MCP endpoint is:

https://mcp.superpositional.io

Authentication uses OAuth. The first time you connect, your tool opens a browser window for you to sign in with your Superpositional account. After that, the token is stored and connections happen automatically.

Setup by tool

Cursor

Add to .cursor/mcp.json in your project root (or global config):

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

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

VS Code (Copilot)

Add to .vscode/mcp.json in your project root:

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

Reload VS Code. The MCP client handles OAuth automatically.

Kiro

Add to .kiro/settings/mcp.json (project-level) or ~/.kiro/settings/mcp.json (global):

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

Save and reload. Kiro handles OAuth 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.

Verify it works

After setup, ask your agent something about your codebase. For example:

"What does the payment service depend on?"
"Review my plan to refactor the auth module"
"What's the blast radius if I change src/handlers/webhook.ts?"

If the agent responds with specific information about your code (file paths, function names, relationships), MCP is working. If it gives generic advice, check Troubleshooting below.

What your agent can do via MCP

Once connected, your agent has access to these capabilities:

Capability	What it does
Ask	Natural-language questions about your codebase, answered with source references
Review plan	Check a proposed plan or design against architecture guards before writing code
Review diff	Run a code diff through the full review pipeline (guards + lenses)
Review spec	Architectural review of a spec or design document
Blast radius	Compute what's affected if you change specific files
System context	Get the role, dependencies, and change implications of a code entity
Diagnose	Root cause analysis from an error message or stack trace
Review issue	Analyse a bug report or feature request against your codebase
List repos	See which repositories are indexed and their status
List guards	See which coding standard guards are active
List rules	See compiled rules for a repository

Your agent discovers and uses these tools automatically based on what you're doing. You don't need to call them directly.

For the full tool reference, see MCP Interface.

Troubleshooting

Agent gives generic answers instead of codebase-specific ones:

Check that your repos are indexed. Open the Repos page in the app and confirm at least one repo shows Ready status.
The MCP server only serves context for indexed repositories. If your repo is still indexing, wait for it to finish.

OAuth window doesn't appear:

Make sure the endpoint URL is exactly https://mcp.superpositional.io — no trailing slash, no path.
Try removing the server config and re-adding it.

Connection drops or token expires:

Your tool should re-authenticate automatically. If it doesn't, remove the MCP server config, restart your tool, and re-add it.

Firewall or proxy issues:

The MCP endpoint requires HTTPS access to mcp.superpositional.io. If you're behind a corporate proxy, ensure this domain is allowed.

Installing MCP

On this page