Skip to main content

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)
Key benefit: Agents get surgical, ranked context instead of raw files, reducing token usage and improving reasoning quality.

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=1 environment variable is set
    • No .tempest/atlas/ directory exists
    • Daemon machinery fails to initialize
Startup:

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
Startup:

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
Process management:
  • Lockfile at .tempest/atlas/daemon.lock arbitrates 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
Startup:

Server Startup & Discovery

From Tempest (Automatic)

When you enable Token Intelligence or start an agent in Tempest:
  1. Tempest’s Rust backend calls start_atlas_index if .tempest/atlas/ doesn’t exist
    • Spawns node .../atlas/dist/mcp/server-entry.js --init --path <project> (background Node process)
    • The AtlasIndexModal polls the check_atlas_db command for .tempest/atlas/atlas.db
    • Background indexing happens while you work
  2. 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
  3. Tempest can also manage a long-lived daemon per project through the start_atlas_daemon / stop_atlas_daemon commands (tracked in atlas-daemons.json in the app data dir), so multiple agents share one server process and file watcher
Configuration: Tempest writes MCP server config to:
  • .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 to opencode.json)
It can also register the server globally for Codex (~/.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:
The server will start in proxy or daemon mode automatically.

MCP Protocol Details

Initialization (Handshake)

When the MCP host starts the server process, the server writes MCP initialization messages to stdout:
The host responds with:
After initialize, the server is ready to receive tool calls via tools/call.

Tools/List

Clients request available tools via tools/list:
The server responds with schemas for all exposed tools (see Tools section below).

Tool Invocation

Clients invoke tools via tools/call:
Server responds with results or error, including:
  • success: boolean — operation succeeded
  • isError?: 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 of atlas_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 all
  • linkedTo (string, optional): Symbol node id — return only assets attached to that symbol via a describes edge
  • format (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 (from atlas_assets)
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 query
  • limit (number, optional): Max results (default: 10, max: 50)
Note: Requires the semantic setting to be on (a one-time ~25 MB MiniLM model download). When it is off, the tool responds with an informational message instead of an error.

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:
The mutation tools 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. 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)
Returns:

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)
Returns:

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 this
    • find_callees <symbol> — functions/methods this calls
    • find_usages <symbol> — all references to this symbol
    • find_type_hierarchy <symbol> — ancestors and descendants
    • find_implementations <interface> — classes implementing this interface
    • find_impact <symbol> — all symbols potentially affected by changes to this
    • find_circular_dependencies — cycles in the codebase
    • find_dead_code — unreferenced symbols
Returns:

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)
Returns:

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)
Returns:

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):
Windsurf (.windsurf/settings.json): Same format as .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
Impact on agent latency:
  • 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
Watchdog mechanisms:
  • 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.js in MCP config
Error: “Database is locked”
  • 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.lock and retry
  • OR: Set ATLAS_NO_DAEMON=1 to 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.log for errors
  • Fallback: ATLAS_NO_DAEMON=1 to run in direct mode

Tool Returns Empty Results

Possible causes:
  1. 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.db exists (Tempest’s check_atlas_db command does this)
  2. Query is too specific
    • Try broader terms (“auth” instead of “authenticate”)
    • Use atlas_explore with broader terms to see what symbols exist
  3. File is excluded
    • Check .gitignore and atlas.json exclude patterns
    • Verify file is in an indexed language

MCP Connection Drops

Error: “MCP server disconnected” or repeated timeouts
  • Cause: Server process crashed or ran out of resources
  • Check: .tempest/atlas/daemon.log for 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=1 for 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.js parses the --init / --path / --download-model / --semantic flags 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
Tempest interacts with this layer only through the Tauri commands above (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)
Result:
  • 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