Atlas MCP Server
The Atlas MCP Server exposes the code knowledge graph via the Model Context Protocol (MCP), allowing Claude, Cline, Roo, and other agents to query semantic code intelligence using standardized tools.Overview
The MCP server is a Node.js process that:- Opens the
.tempest/atlas/SQLite database for a project - Implements the MCP specification (tools, resources, protocol)
- Exposes Atlas functionality as AI-readable tools
- Handles concurrent requests from multiple agents
- Manages its own lifecycle (daemon, proxy, direct modes)
Architecture & Modes
The MCP server supports three runtime modes, decided at startup based on configuration and availability:1. Direct Mode
One process = one MCP client over stdio- Simplest setup
- No background daemon
- Process exits when client disconnects
- Used when:
ATLAS_NO_DAEMON=1environment variable is set- No
.tempest/atlas/directory exists - Daemon machinery fails to initialize
2. Proxy Mode
Thin stdio ← → socket bridge to a shared daemon- Used by default when
.tempest/atlas/exists and daemon is available - Proxy is lightweight, exits when agent disconnects
- Daemon persists in background, serves multiple clients
- Proxy carries PPID watchdog to gracefully tear down if host is killed
3. Daemon Mode
Shared background process with Unix socket or named pipe- Spawned on-demand by the first proxy
- Detached process, not a child of any host
- Survives individual agent disconnects
- Exits after client-refcount timeout (~5 minutes idle)
- Logs to
.tempest/atlas/daemon.log
- Lockfile at
.tempest/atlas/daemon.lockarbitrates startup races - Multiple launchers may race to spawn; only one wins
- Winner acquires O_EXCL lock, binds socket, serves all proxies
- Losers detect the lock, connect to winner’s socket
Server Startup & Discovery
From Tempest (Automatic)
When you enable Token Intelligence or start an agent in Tempest:-
Tempest’s Rust backend calls
start_atlas_indexif.tempest/atlas/doesn’t exist- Spawns
node .../atlas/dist/mcp/server-entry.js --init --path <project>(background Node process) - The
AtlasIndexModalpolls thecheck_atlas_dbcommand for.tempest/atlas/atlas.db - Background indexing happens while you work
- Spawns
-
Tempest writes MCP config files (below) that point agents at the server
- Each entry runs
node .../atlas/dist/mcp/server-entry.js --path <project> - The agent’s MCP host spawns the server process and connects over stdio
- The server immediately prints MCP handshake to stdout
- Each entry runs
-
Tempest can also manage a long-lived daemon per project through the
start_atlas_daemon/stop_atlas_daemoncommands (tracked inatlas-daemons.jsonin the app data dir), so multiple agents share one server process and file watcher
.mcp.json(Claude Code, Cline, Roo, Zed, Windsurf standard).cursor/mcp.json(Cursor).gemini/settings.json(Google Gemini).kiro/settings/mcp.json(AWS Kiro)opencode.jsonc(falls back toopencode.json)
~/.codex/config.toml, under [mcp_servers.atlas]) and Goose (~/.config/goose/profiles.yaml). Matching .gitignore entries are added alongside the project-level files so they stay out of version control.
Example .mcp.json:
Manual Setup (Outside Tempest)
To connect any agent to Atlas:MCP Protocol Details
Initialization (Handshake)
When the MCP host starts the server process, the server writes MCP initialization messages to stdout:initialize, the server is ready to receive tool calls via tools/call.
Tools/List
Clients request available tools viatools/list:
Tool Invocation
Clients invoke tools viatools/call:
success: boolean— operation succeededisError?: boolean— tool result is an error (false for recoverable “no index” conditions)content: TextContent[]— tool output
Exposed Tools
By default the server lists a deliberately small read-only surface. Every other tool is a strict subset ofatlas_explore, and listing them was steering agents toward worse picks.
atlas_explore
The primary read-equivalent: ask a natural-language question or name the symbols you care about, and one capped call returns the verbatim, line-numbered source of the relevant symbols grouped by file, plus the call path among them (dynamic-dispatch hops included) and a blast-radius summary of what depends on them. Usually the only tool an agent needs. Arguments:query(string, required): Symbol names, file names, or a natural-language question (e.g., “How does user login work?”)maxFiles(number, optional): Maximum number of files to include source from (default: 12)
atlas_assets
List human-attached knowledge — markdown notes and other docs a developer explicitly attached to the codebase. Treat their presence as intentional context, not a scan of the disk. Arguments:contentType(string, optional): MIME prefix filter (e.g.,text/markdown,text/); omit to list alllinkedTo(string, optional): Symbol node id — return only assets attached to that symbol via adescribesedgeformat(string, optional):"markdown"(default) or"json"(structured array)
atlas_asset_content
Return the extracted text of one asset by id. Content is already capped at attach time — no pagination. Arguments:id(string, required): Asset id (fromatlas_assets)
atlas_semantic_search
Pure vector-similarity search across code symbols and attached assets. Skips graph traversal when you want ranked candidates directly (e.g., “find notes and code about auth session expiry”). Arguments:query(string, required): Natural-language querylimit(number, optional): Max results (default: 10, max: 50)
Legacy tools
atlas_search, atlas_node, atlas_graph, atlas_file_dependencies, and atlas_status remain implemented and callable, but they are no longer listed by default because every one is a strict subset of atlas_explore. Re-enable them per-agent with the ATLAS_MCP_TOOLS environment variable:
atlas_asset_add / atlas_asset_remove exist on the handler surface (the Knowledge Base Docs panel uses them) but are not part of the read-only default list.
atlas_search
Search the code graph by name or full-text. Purpose: Find symbols matching a query, ranked by relevance. Arguments:query(string, required): Search term (e.g., “authenticate”, “User”, “handleSubmit”)limit(number, optional): Max results to return (default: 20)
atlas_node
Retrieve detailed information about a specific symbol. Purpose: Get a symbol’s definition, metadata, and related symbols. Arguments:symbol(string, required): Symbol name or qualified name (e.g., “authenticate” or “src/auth.ts::authenticate”)includeCode(boolean, optional): Include source code (default: true)kind(string, optional): Filter by node kind (e.g., “function”, “class”)includeRelated(boolean, optional): Include callers, callees, usages (default: false)
atlas_graph
Traverse the code graph to answer structural questions. Purpose: Explore relationships: “Who calls this?”, “What does this class extend?”, “Where is this variable used?” Arguments:query(string, required): Graph query in format<operation> <symbol>find_callers <symbol>— functions/methods that call thisfind_callees <symbol>— functions/methods this callsfind_usages <symbol>— all references to this symbolfind_type_hierarchy <symbol>— ancestors and descendantsfind_implementations <interface>— classes implementing this interfacefind_impact <symbol>— all symbols potentially affected by changes to thisfind_circular_dependencies— cycles in the codebasefind_dead_code— unreferenced symbols
atlas_status
Get project index status and statistics. Purpose: Check if index exists, how fresh it is, and get graph statistics. Arguments:projectPath(string, optional): Project path (default: cwd or discovered)
atlas_file_dependencies
Get files that a source file depends on. Purpose: Understand import structure and find integration points. Arguments:filePath(string, required): Path to file (relative to project root)
Agent Integration Examples
Claude (Claude Code)
Claude automatically uses Atlas tools when available. Example:Cline / Roo
Cline and Roo read MCP server config from.mcp.json and connect to Atlas automatically:
Zed, Windsurf, Cursor
These editors include their own AI agents with MCP support. Add Atlas to their MCP config: Zed (.zed/settings.json):.mcp.json.
Cursor (.cursor/mcp.json):
Standard MCP format.
Performance & Optimization
Tool Response Times
atlas_search: 10-100ms (depends on query specificity)atlas_explore: 50-500ms (includes graph traversal and code extraction)atlas_node: 5-50ms (cached queries)atlas_graph: 50-1000ms (depends on graph depth and size)atlas_status: < 5ms
- Per tool call: 100-500ms (network + execution)
- Typical agent query: 1-3 tool calls + LLM inference
- Total latency: Usually 2-5 seconds (LLM dominates)
Database Concurrency
Atlas uses SQLite with WAL (Write-Ahead Log) mode:- Multiple MCP clients can read simultaneously
- Background file watcher can write while tools are running
- No locks needed for reads (except when sync is in progress)
- Sync holds a file lock for 1-10 seconds on typical changes
- PPID watchdog (proxy mode): If host process dies (SIGKILL), proxy detects parent process death and shuts down gracefully
- Liveness watchdog (daemon mode): Heartbeat monitor that detects main-thread hangs and SIGKILLs the process if unresponsive for 10+ seconds
- Idle timeout (daemon mode): After 5 minutes with no clients, daemon exits to free resources
Token Efficiency
Measured across the benchmark suite in BENCHMARKS.md: agents using Atlas see a median 76% reduction in total tokens, with per-repo savings up to 86%. The per-query table below is illustrative:
Savings come from:
- Returning ranked search results instead of whole files
- Providing symbol metadata instead of raw code parsing
- Showing relationships instead of requiring file reads
Troubleshooting
Server Won’t Start
Error: “Cannot resolve CLI script path to spawn the daemon”- Cause: Node entry point (
process.argv[1]) is invalid - Fix: Use full path to
server-entry.jsin MCP config
- Cause: Another process is indexing or the database is corrupted
- Fix: Wait for indexing to complete, or remove
.tempest/atlas/and re-index
Daemon Won’t Start
Error: “Could not bind socket” or “daemon.sock exists”- Cause: Stale socket from previous daemon or race condition
- Fix: Remove
.tempest/atlas/daemon.lockand retry - OR: Set
ATLAS_NO_DAEMON=1to run in direct mode instead
Proxy/Client Won’t Connect
Error: “ECONNREFUSED: connection refused”- Cause: Daemon didn’t start or socket isn’t ready
- Fix: Check
.tempest/atlas/daemon.logfor errors - Fallback:
ATLAS_NO_DAEMON=1to run in direct mode
Tool Returns Empty Results
Possible causes:-
Index is empty (no files indexed yet)
- Re-run the initial index:
node .../atlas/dist/mcp/server-entry.js --init --path <project> - Check that
.tempest/atlas/atlas.dbexists (Tempest’scheck_atlas_dbcommand does this)
- Re-run the initial index:
-
Query is too specific
- Try broader terms (“auth” instead of “authenticate”)
- Use
atlas_explorewith broader terms to see what symbols exist
-
File is excluded
- Check
.gitignoreandatlas.jsonexclude patterns - Verify file is in an indexed language
- Check
MCP Connection Drops
Error: “MCP server disconnected” or repeated timeouts- Cause: Server process crashed or ran out of resources
- Check:
.tempest/atlas/daemon.logfor errors - Solution: Restart agent or Tempest
High Memory Usage
- Cause: Large graph or long-running daemon with many symbols
- Solution: Restart daemon (kill the process with the PID from
.tempest/atlas/daemon.lock) - Or: Use
ATLAS_NO_DAEMON=1for fresh process per agent
Architecture
The MCP server ships inside the published@usetempest/atlas npm package (Tempest stages it into src-tauri/resources/atlas/ at install time), so its source tree is not part of this repository. Conceptually it is layered as:
- Entry point —
dist/mcp/server-entry.jsparses the--init/--path/--download-model/--semanticflags and picks a runtime mode - Direct mode — one stdio server process per MCP client, no daemon
- Proxy mode — a short-lived stdio-to-socket bridge that forwards requests to a shared daemon; carries a PPID watchdog so the proxy tears down gracefully if its host process is killed
- Daemon mode — a detached, long-lived process serving many proxies over a socket or named pipe, with a liveness watchdog (a heartbeat that kills the process if the main thread hangs for 10+ seconds) and an idle timeout (~5 minutes with no clients)
- Query engine — executes graph queries against the SQLite index and dispatches tool calls
start_atlas_index, start_atlas_daemon / stop_atlas_daemon, atlas_mcp_tools / atlas_mcp_call for one-shot stdio MCP bridging, get_atlas_graph, atlas_query) and the MCP config files it writes.
Advanced Configuration
Disable Daemon Mode
Set environment variable to force direct mode (no background daemon):Custom Daemon Paths
The daemon socket path is computed from:- Project root
.tempest/atlas/directory - Hash of the absolute path (prevents collisions with symlinks)
- Linux/macOS:
/run/user/1000/atlas_<hash>.sock - Windows:
//./pipe/atlas_<hash>
Logging
Daemon logs to.tempest/atlas/daemon.log. Enable verbose logging:
Future Enhancements
Planned features for the MCP server:- WebSocket transport — For remote agents/IDEs
- Batch operations — Multiple queries in one RPC call
- Caching layer — Per-session query result cache
- Streaming responses — Large subgraphs streamed incrementally
- Custom resolvers — Plugin system for language-specific analysis
- Agent profiling — Metrics on tool usage and response times