MCP Server
The Constellation MCP Server connects your AI coding assistants to Constellation's powerful codebase intelligence system. It exposes a single code_intel tool that runs JavaScript against Constellation's code intelligence API.
Installation
-
It is strongly recommended to use the Constellation CLI command
const initto automatically configure your AI coding tools in your project, and to commit those configurations to your project's source control repository (for AI assistants that support project-level configuration). -
The CLI utility also configures custom hooks for supported AI tools, which further optimizes LLM organic utilization of Constellation tools.
-
If using our 🧩 Official Plugins you do not need to add the Constellation MCP server configuration independently as it comes bundled with the plugins.
Manually configure the Constellation MCP server by following the directions below for your preferred AI tools.
Antigravity
Use the official Constellation Plugin for Google Antigravity. Execute the following command in your terminal:
agy plugin install https://github.com/ShiftinBits/constellation-antigravity
Claude Code
Use the official Constellation Plugin for Claude Code.
Add the following properties to the root of the .claude/settings.json file in your project:
"extraKnownMarketplaces": {
"constellation-plugins": {
"source": {
"source": "github",
"repo": "ShiftinBits/constellation-claude"
}
}
},
"enabledPlugins": {
"constellation@constellation-plugins": true
}
Codex
Use the official Constellation Plugin for Codex. Execute the following commands in your terminal:
codex plugin marketplace add ShiftinBits/constellation-codex
codex plugin add constellation@constellation-plugins
To configure the MCP server without the plugin, add the following section to the Codex .codex/config.toml file in your project. Codex forwards the CONSTELLATION_ACCESS_KEY variable from your environment to the server through env_vars:
[mcp_servers.constellation]
command = "npx"
args = ["-y", "@constellationdev/mcp@latest"]
env_vars = ["CONSTELLATION_ACCESS_KEY"]
enabled = true
enabled_tools = ["code_intel"]
Copilot CLI
Use the official Constellation Plugin for Copilot CLI. Execute the following commands in your terminal:
copilot plugin marketplace add ShiftinBits/constellation-copilot
copilot plugin install constellation@constellation-plugins
Cursor
There are multiple alternatives for configuring MCP servers in your project for use with Cursor.
-
Recommended: Click the following button to automatically install the Constellation MCP server with Cursor:
-
Add the following property to the
mcpServersobject of the.cursor/mcp.jsonfile in your project:"constellation": {"type": "stdio","command": "npx","args": ["-y","@constellationdev/mcp@latest"],"env": {"CONSTELLATION_ACCESS_KEY": "${env:CONSTELLATION_ACCESS_KEY}"}}
JetBrains
Add the following property to the mcpServers object of the .ai/mcp/mcp.json file in your project:
"constellation": {
"command": "npx",
"args": [
"-y",
"@constellationdev/mcp@latest"
],
"tools": ["code_intel"],
"env": {
"CONSTELLATION_ACCESS_KEY": "CONSTELLATION_ACCESS_KEY"
}
}
Kilo Code
Add the following property to the mcpServers object of the .kilocode/mcp.json file in your project:
"constellation": {
"command": "npx",
"args": [
"-y",
"@constellationdev/mcp@latest"
],
"alwaysAllow": ["code_intel"],
"env": {
"CONSTELLATION_ACCESS_KEY": "${env:CONSTELLATION_ACCESS_KEY}"
}
}
OpenCode
Add the plugin to your project's opencode.json:
{
"plugin": ["@constellationdev/opencode"]
}
OpenCode will automatically install the plugin at startup.
VSCode
There are multiple alternatives for configuring MCP servers in your project for use with GitHub Copilot.
-
Recommended: Click the following button to automatically install the Constellation MCP server with VSCode:
-
Add the following property to the
serversobject of the.vscode/mcp.jsonfile in your project:"constellation": {"type": "stdio","command": "npx","args": ["-y","@constellationdev/mcp@latest"],"tools": ["code_intel"],"env": {"CONSTELLATION_ACCESS_KEY": "CONSTELLATION_ACCESS_KEY"}}
Windsurf
Add the following property to the mcpServers object of the Windsurf ~/.codeium/windsurf/mcp_config.json file:
"constellation": {
"command": "npx",
"args": [
"-y",
"@constellationdev/mcp@latest"
],
"tools": ["code_intel"],
"env": {
"CONSTELLATION_ACCESS_KEY": "${env:CONSTELLATION_ACCESS_KEY}"
}
}
Other / Generic
Typically you will find an mcpServers or servers section in a JSON configuration file for your AI tooling, or perhaps a .mcp.json file in your project root folder. Add an entry for the Constellation MCP server to the proper configuration file in the respective section.
| Property | Value |
|---|---|
| name | constellation |
| type | stdio |
| command | npx |
| args | -y, @constellationdev/mcp@latest |
| allow tools | code_intel |
| env vars | CONSTELLATION_ACCESS_KEY |
JSON Example:
"constellation": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@constellationdev/mcp@latest"
],
"env": {
"CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
}
}
Benefits
Speed
Code Mode is 10-15x faster than traditional sequential tool calls. Complex analyses that would take 30+ seconds now complete in 2-3 seconds.
Composability
Your AI can combine multiple API calls with custom logic, parallel execution via Promise.all(), and sophisticated data transformations all in a single execution.
Team-Wide Intelligence
- All queries operate on your team's shared knowledge graph
- Consistent and accurate results across all team members
- Synchronized with your project's latest indexed changes
Graph-Powered Analysis
- Deep understanding of code relationships and dependencies
- Cross-file analysis that spans your entire codebase
- Pattern recognition and architectural insights
Requirements
- AI Assistant: Compatible AI coding assistant with MCP support (e.g., Claude Code, GitHub Copilot)
- Node.js: Version 20 or higher
- MCP protocol: Supports MCP clients on protocol version 2026-07-28, plus older clients that connect with the standard
initializehandshake - Constellation CLI: Must have a configured and indexed project (a
constellation.jsonat your git repository root) - Authentication: Valid Constellation access key in the
CONSTELLATION_ACCESS_KEYenvironment variable (const authsets it for you)
Configuration
The MCP server reads the project and branch from constellation.json, and the settings below from environment variables.
| Variable | Default | Description |
|---|---|---|
CONSTELLATION_ACCESS_KEY | (none, required) | Your Constellation access key (starts with ak:) |
CONSTELLATION_API_URL | https://api.constellationdev.io | Overrides the API endpoint |
CONSTELLATION_SANDBOX_ISOLATION | convenience | Set to hardened to run each code_intel call in a separate child process with a hard memory limit |
CONSTELLATION_INCLUDE_SNIPPETS | enabled | Set to false to stop adding local source snippets to results. Snippets are read from your local files and are never sent to Constellation |
CONSTELLATION_USAGE_METRICS | enabled | Set to false or 0 to disable usage metrics (see below). Other values, such as no or off, leave them enabled |
CONSTELLATION_AUDIT_LOG | disabled | Set to true to write a JSON audit trail of code_intel calls to stderr |
DEBUG | disabled | Set to any value for verbose logging on stderr |
Usage metrics: After each code_intel call (other than plugin hook calls), the MCP server sends a usage event to the Constellation API. The event contains the project ID, branch name, which API methods ran, an estimated token count for each result, and the call duration. It contains no source code, no code_intel program text, and no query results.
Quick Start
-
Install the MCP server in your AI assistant (see Installation above)
-
Authenticate:
const auth -
Initialize your project (creates
constellation.json):const init -
Index your codebase:
const index -
Ask your AI assistant questions like:
- "Find all uses of the
UserServiceclass" - "What would be affected if I change this function?"
- "Are there any circular dependencies in this module?"
- "Summarize the architecture of this codebase"
- "Find all uses of the
Your AI assistant will automatically utilize Constellation to provide insightful and accurate answers!