MCP Interface

Connect AI coding tools to Superpositional via MCP for structured codebase context.

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, it queries Superpositional through MCP and gets back structured data — entities, relationships, search results, dependency graphs, and more.

This is the same indexed data 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

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.

Available tools

The MCP server exposes the following tools. Your AI agent discovers and uses these automatically — you don't need to call them directly.

Observe

Tool	Description
`list_repos`	List all indexed repositories in your org with status and metadata
`get_repo`	Get detailed status of a specific repository
`list_documents`	List generated documents (summaries, changelogs, reviews)
`get_document`	Retrieve a specific document by ID
`get_staleness_reports`	Get staleness findings for a document
`list_issues`	List issues tracked by Superpositional
`get_issue`	Get details of a specific issue

Context

Tool	Description
`search`	Semantic code search across a repository
`query_entities`	Search for code entities (functions, classes, modules) by name
`query_relations`	Traverse the dependency graph for an entity
`get_blast_radius`	Compute what's affected by file changes
`get_pr_changes`	Inspect file changes in a pull request
`search_claims`	Search structured claims extracted from documents
`search_docs`	Search document content

Q&A

Tool	Description
`ask`	Ask a natural-language question about a repository

Feedback

Tool	Description
`review_plan`	Get architecture and guardrail feedback on a plan before writing code
`review_diff`	Review a code diff through guard agent lenses
`review_spec`	Review a spec document through guard agent lenses
`get_actionable_issues`	Get open issues that can be actioned as fixes

Diagnose

Tool	Description
`diagnose`	Describe a fault or error and get root cause analysis

Steering

Tool	Description
`list_guards`	List all guards with their enabled/disabled status
`toggle_guard`	Enable or disable a guard for your org
`list_rules`	List compiled rules for a repository

Act

Tool	Description
`generate_document`	Trigger document generation (summary, changelog, architecture doc)

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.

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 internet access. If you're behind a corporate proxy, ensure mcp.superpositional.io is allowed.

MCP Interface

On this page