The Constellation MCP server provides graph-backed code intelligence for AI coding assistants, enabling deep structural analysis of a codebase without transmitting source code (only metadata is sent, never raw source).
Core capabilities:
Search & inspect symbols — Find definitions of functions, classes, and variables (searchSymbols, getSymbolDetails)
Analyze dependencies — Discover what a file depends on (getDependencies) and what depends on it (getDependents)
Trace symbol usage — Track all usages of a symbol across the codebase (traceSymbolUsage)
Explore call graphs — Map how a symbol is invoked (getCallGraph)
Impact analysis — Assess blast radius and breaking-change risk before modifying code (impactAnalysis)
Detect circular dependencies — Find circular dependency chains (findCircularDependencies)
Find orphaned/dead code — Identify unused exports or unreferenced code (findOrphanedCode)
Architecture overview — Get a high-level structural view of a codebase (getArchitectureOverview)
Compose complex queries — Execute arbitrary JavaScript with top-level await and run parallel API calls
Browse the API — List available methods and TypeScript type definitions via api.listMethods() and api.help()
Additional features:
Multi-language support: TypeScript, JavaScript, Python, and more (check via api.getCapabilities())
Branch-aware indexing scoped to the current git branch
Access control enforced via API keys
Designed for structural questions (definitions, callers, impact) — use Grep/Read for text search instead
Integrates with Git to provide branch-aware code intelligence, ensuring that codebase metadata and analysis remain discrete and isolated between different development branches.
Provides GitHub Copilot with structured codebase metadata and relationship analysis, enabling deeper context for code intelligence and assistant-led development.
Give your AI coding assistant instant, intelligent access to your entire codebase's structure, dependencies, and relationships without transmitting any source code. Constellation provides code intelligence as a service to AI coding assistant tools.
Add the Constellation MCP server to your AI assistant project-level config (or system-level if your tooling doesn't support project-level configuration):
{
"mcpServers": {
"constellation": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@constellationdev/mcp@latest"],
"env": {
"CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
}
}
}
}
The above example is a generic format for the .mcp.json file used by some tools such as VSCode and Claude Code.
Rather than directly configuring the MCP server, it is recommended to install and utilize official Constellation Plugins for optimal performance and behavior!
For information on configuring other AI assistants see the MCP Server > Installation doc.
For further instructions regarding authentication, project setup, and configuration refer to the official docs.
Related MCP server: NOMIK
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#4A90E2', 'primaryTextColor': '#EEEEEE', 'primaryBorderColor': '#2B2C34', 'lineColor': '#4A90E2', 'secondaryColor': '#1F1F28', 'tertiaryColor': '#0B0C10', 'edgeLabelBackground': '#1F1F28' }}}%%
flowchart LR
subgraph local["💻 Your Environment"]
direction TB
code["📂 Source Code"]
cli["⚙️ Constellation CLI"]
ai["🤖 AI Coding Assistant"]
mcp["🧩 Constellation MCP"]
code --> cli
end
subgraph cloud["✨ Constellation Service"]
direction TB
api["🔌 API"]
graphdb[("🧠 Knowledge Graph")]
api <--> graphdb
end
cli a1@-->|"Metadata Upload"| api
ai <-->|"Tool Calls"| mcp
mcp a2@<-->|"Queries"| api
a1@{ animation: fast }
a2@{ animation: fast }
style local fill:#1F1F28
style cloud fill:#1F1F28,stroke:#4A90E2
style cli stroke:#4A90E2
style mcp stroke:#4A90E2
style api stroke:#4A90E2
style graphdb stroke:#4A90E2Parse and Analyze: The CLI tool analyzes source code in your environment, extracting structural metadata (functions, classes, variables, imports, calls, references, etc.)
Upload: Only the metadata is securely sent to Constellation, never raw source code
Query: AI assistants use the Constellation MCP tool to send complex queries, and get rapid answers derived from the knowledge graph
Find the full and comprehensive documentation at docs.constellationdev.io/mcp/
Installation & Setup - Configure for Claude Code, Cursor, GitHub Copilot, and more
Tools Reference - Code Mode API and available methods
Troubleshooting - Common issues and solutions
No source code transmission - Only metadata and relationships
Access control - API keys required for all requests
Branch isolation - Each git branch maintains discrete code intelligence
For comprehensive information regarding privacy and security, see the official Privacy & Security documentation.
Documentation: docs.constellationdev.io
Report Issues: GitHub Issues
AGPL-3.0 - See LICENSE for details.
Copyright © 2026 ShiftinBits Inc.
DECISION RULE: Structure questions → this tool. Text search → Grep.
Before using Grep, ask: Is this a STRUCTURE question (definitions, callers, impact) or a TEXT question (strings, config)?
QUICK START: return await api.searchSymbols({query: "AuthService"}) — simple queries are one-liners.
Run api.listMethods() for full API reference with signatures and descriptions.
Run api.help("methodName") for inline TypeScript type definitions — no resource reads needed.
Compose: const [impact, deps] = await Promise.all([api.impactAnalysis({symbolId}), api.getDependents({filePath})]);
WHY THIS TOOL: Graph-backed intelligence finds indirect relationships, transitive dependencies, and breaking change risks that text search cannot detect.
"What uses X?" disambiguation: getDependents (file imports) vs getCallGraph (call chain) vs traceSymbolUsage (all usages).
USE IMMEDIATELY WHEN: • BEFORE using Edit on a function/class → run impactAnalysis({symbolId}) first • BEFORE exploring an unfamiliar codebase → run getArchitectureOverview() • BEFORE refactoring → trace getDependencies + getDependents for blast radius • Running 3+ Grep calls for structure? STOP → use code_intel instead
TOP 5 QUESTIONS (query is case-insensitive substring match): • "Where is X defined?" / "Find function Y" → searchSymbols({query}) • "What calls X?" / "What imports this?" → getDependents({filePath}) or getCallGraph({symbolId}) • "What does X depend on?" → getDependencies({filePath}) • "Safe to modify X?" / "Blast radius?" → impactAnalysis({symbolId}) • "Find dead code" / "Unused exports?" → findOrphanedCode() • "Complex functions?" / "Refactoring targets?" → searchSymbols results include complexity.cyclomaticComplexity + complexityRisk per function
NOT FOR: literal string search, log messages, config values, or reading source code. Use Grep/Glob/Read for those.
Supports TypeScript, JavaScript, Python, and more — run api.getCapabilities() to check your project.
File-path-scoped methods (getDependencies, getDependents, getCallGraph, traceSymbolUsage, impactAnalysis) reject calls whose filePath extension is not in the project's configured languages with UNSUPPORTED_LANGUAGE — check api.getCapabilities() first.
WRONG TOOL SIGNAL: If you've run 3+ Grep calls for structure (callers, dependencies, impact), STOP and use code_intel instead. Typical workflow: code_intel to find (results include source snippets) → Edit to modify
Sandbox limits: 50 api.* calls per execution, 128 MB memory, 100 KB max code size, limit max 100 on any method with a limit param. Pure JS only — no require/import/fs/net/process (see constellation://docs/guide for full restrictions).
IMPORTANT: The cwd parameter is required — always set it to the target project directory path.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path to the project directory being queried. Used to locate the correct constellation.json by finding the git repository root. Set this to the root of the repository or workspace folder you are working in. | |
| code | Yes | JavaScript code to execute. Can use top-level await. Available API methods: searchSymbols, getSymbolDetails, getDependencies, getDependents, findCircularDependencies, traceSymbolUsage, getCallGraph, impactAnalysis, findOrphanedCode, getArchitectureOverview | |
| timeout | No | Optional execution-time override in milliseconds. When omitted, the sandbox derives the timeout from the static complexity of your code (heavier api.* methods raise the budget) and clamps the result to [1000, 60000]. The breakdown is returned in the response so you can see what was applied. Explicit values still win and are clamped to the same range. |
| Name | Required | Description |
|---|---|---|
| logs | No | |
| time | No | |
| error | No | |
| result | No | |
| success | Yes | |
| asOfCommit | No | |
| lastIndexedAt | No | |
| resultContext | No | |
| timeoutBreakdown | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: sandbox limits (50 api calls, 128 MB memory, 100 KB code), timeout derivation, UNSUPPORTED_LANGUAGE rejection, and requirement for cwd to locate constellation.json. These reveal important constraints and behaviors beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but verbose. It uses headings, bullet points, and code examples effectively, and front-loads with the decision rule. However, some sections (e.g., sandbox limits, top 5 questions) are longer than necessary. A slightly more concise version would maintain completeness while improving scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple API methods, sandbox restrictions, dynamic timeouts, language support), the description covers all essential aspects: when to use, how to compose calls, error conditions (UNSUPPORTED_LANGUAGE), and limitations. Output schema exists, so return value documentation is not needed. Complete for its context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning: for 'code', it lists available API methods; for 'timeout', explains dynamic derivation and clamping; for 'cwd', explains its role in locating configuration. This enriches the agent's understanding beyond the schema, though the schema already covers parameter types and descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for structure questions (definitions, callers, impact) versus text search (Grep). It uses specific verbs like 'find', 'trace', 'search' and explicitly distinguishes from sibling tools (Grep, Glob, Read) even though no siblings are listed. The 'WRONG TOOL SIGNAL' and 'NOT FOR' sections reinforce purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Excellent guidelines: 'DECISION RULE' distinguishes structure vs text; 'USE IMMEDIATELY WHEN' lists specific scenarios before editing, exploring, refactoring; 'TOP 5 QUESTIONS' maps common intents to methods; 'NOT FOR' lists exclusions. Also provides workflow examples and wrong-tool signals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
With only one tool, there is no ambiguity; the tool's purpose is clearly defined and distinct from any other.
A single tool name ensures perfect naming consistency; there are no naming conflicts or inconsistencies.
The server attempts to cover a broad range of code intelligence operations (symbol search, dependency analysis, impact analysis, etc.) but condenses them into a single tool, which is insufficient for discoverability and typical MCP expectations.
The tool's API covers many code intelligence operations (symbols, dependencies, impact, dead code), with minor gaps like source reading explicitly delegated elsewhere, making it fairly complete for its stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Vendor intelligence for AI coding agents choosing developer tools and stacks.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ShiftinBits/constellation-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
