Skip to main content

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​

TIPS: Automatic Setup and Configuration
  • It is strongly recommended to use the Constellation CLI command const init to 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.

Google Antigravity Antigravity

📚 Official Documentation 🔗

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 Claude Code

📚 Official Documentation 🔗

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
}

OpenAICodex

📚 Official Documentation 🔗

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"]

GitHub Copilot Copilot CLI

📚 Official Documentation 🔗

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 Cursor

📚 Official Documentation 🔗

There are multiple alternatives for configuring MCP servers in your project for use with Cursor.

  1. Recommended: Click the following button to automatically install the Constellation MCP server with Cursor:

    Install MCP Server

  2. Add the following property to the mcpServers object of the .cursor/mcp.json file in your project:

    "constellation": {
    "type": "stdio",
    "command": "npx",
    "args": [
    "-y",
    "@constellationdev/mcp@latest"
    ],
    "env": {
    "CONSTELLATION_ACCESS_KEY": "${env:CONSTELLATION_ACCESS_KEY}"
    }
    }

JetBrains

📚 Official Documentation 🔗

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

📚 Official Documentation 🔗

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

📚 Official Documentation 🔗

Add the plugin to your project's opencode.json:

{
"plugin": ["@constellationdev/opencode"]
}

OpenCode will automatically install the plugin at startup.

VSCode

📚 Official Documentation 🔗

There are multiple alternatives for configuring MCP servers in your project for use with GitHub Copilot.

  1. Recommended: Click the following button to automatically install the Constellation MCP server with VSCode:

    Install in VS Code

  2. Add the following property to the servers object of the .vscode/mcp.json file in your project:

    "constellation": {
    "type": "stdio",
    "command": "npx",
    "args": [
    "-y",
    "@constellationdev/mcp@latest"
    ],
    "tools": ["code_intel"],
    "env": {
    "CONSTELLATION_ACCESS_KEY": "CONSTELLATION_ACCESS_KEY"
    }
    }

Windsurf

📚 Official Documentation 🔗

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.

PropertyValue
nameconstellation
typestdio
commandnpx
args-y, @constellationdev/mcp@latest
allow toolscode_intel
env varsCONSTELLATION_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 initialize handshake
  • Constellation CLI: Must have a configured and indexed project (a constellation.json at your git repository root)
  • Authentication: Valid Constellation access key in the CONSTELLATION_ACCESS_KEY environment variable (const auth sets it for you)

Configuration​

The MCP server reads the project and branch from constellation.json, and the settings below from environment variables.

VariableDefaultDescription
CONSTELLATION_ACCESS_KEY(none, required)Your Constellation access key (starts with ak:)
CONSTELLATION_API_URLhttps://api.constellationdev.ioOverrides the API endpoint
CONSTELLATION_SANDBOX_ISOLATIONconvenienceSet to hardened to run each code_intel call in a separate child process with a hard memory limit
CONSTELLATION_INCLUDE_SNIPPETSenabledSet 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_METRICSenabledSet to false or 0 to disable usage metrics (see below). Other values, such as no or off, leave them enabled
CONSTELLATION_AUDIT_LOGdisabledSet to true to write a JSON audit trail of code_intel calls to stderr
DEBUGdisabledSet 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​

  1. Install the MCP server in your AI assistant (see Installation above)

  2. Authenticate:

    const auth
  3. Initialize your project (creates constellation.json):

    const init
  4. Index your codebase:

    const index
  5. Ask your AI assistant questions like:

    • "Find all uses of the UserService class"
    • "What would be affected if I change this function?"
    • "Are there any circular dependencies in this module?"
    • "Summarize the architecture of this codebase"

Your AI assistant will automatically utilize Constellation to provide insightful and accurate answers!