MCP Server

Use Atlas as a Model Context Protocol server in Claude Desktop, Cursor, and other MCP clients.

Atlas exposes a Model Context Protocol (MCP) server that gives any MCP-compatible client access to your semantic layer and validated SQL execution.

Prerequisites

Atlas project set up (bun install)
ATLAS_DATASOURCE_URL pointing to your analytics database
An MCP-compatible client (Claude Desktop, Cursor, or any stdio/SSE client)
LLM provider API key configured in the client (the MCP server itself does not call an LLM)

Quick Start

bun run mcp              # Start MCP server on stdio
bun run dev:mcp           # Start with hot reload
bun run atlas -- mcp      # Same as bun run mcp

Claude Desktop

Add Atlas to your Claude Desktop configuration at ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atlas": {
      "command": "bun",
      "args": ["run", "mcp"],
      "cwd": "/path/to/your/atlas/project",  // Must point to your Atlas project root
      "env": {
        "ATLAS_DATASOURCE_URL": "postgresql://user:pass@host:5432/db",
        "ATLAS_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."     // Your LLM provider API key
      }
    }
  }
}

Cursor

In Cursor settings, add an MCP server with:

Command: bun
Args: ["run", "mcp"]
Working directory: Your Atlas project root

Other MCP Clients

Any client that supports the stdio transport can use Atlas. The server reads JSON-RPC on stdin and writes responses to stdout. Logs go to stderr.

SSE Transport

For remote or containerized setups, use the SSE (Server-Sent Events) transport:

# Start SSE transport on default port 8080
bun ./packages/mcp/bin/serve.ts --transport sse
# Custom port for SSE transport
bun ./packages/mcp/bin/serve.ts --transport sse --port 9090
# Restrict CORS to a specific origin (default: *)
bun ./packages/mcp/bin/serve.ts --transport sse --cors-origin "https://example.com"

Flag	Default	Description
`--transport`	`stdio`	`stdio` or `sse`
`--port`	`8080`	Port for SSE transport
`--cors-origin`	`*` (or `ATLAS_CORS_ORIGIN`)	CORS allowed origin

The SSE endpoint is available at http://localhost:8080/mcp.

Available Tools

The MCP server exposes two tools:

explore

Read files from the semantic layer directory. Accepts bash commands scoped to the semantic/ directory.

command: "cat catalog.yml"
command: "grep -r revenue entities/"
command: "ls entities/"

This is the same explore tool the agent uses -- read-only, path-traversal protected.

executeSQL

Execute a validated SQL query against the analytics datasource.

sql: "SELECT COUNT(*) FROM orders"
explanation: "Count total orders"
connectionId: "warehouse"  (optional)

All SQL validation applies: SELECT-only, table whitelist, auto-LIMIT, statement timeout, and audit logging. See SQL Validation Pipeline.

Available Resources

The MCP server exposes the semantic layer as read-only resources:

URI	Description
`atlas://semantic/catalog`	Data catalog (`catalog.yml`)
`atlas://semantic/glossary`	Business glossary (`glossary.yml`)
`atlas://semantic/entities/{name}`	Entity schema (e.g., `entities/orders.yml`)
`atlas://semantic/metrics/{name}`	Metric definitions (e.g., `metrics/orders.yml`)

Entity and metric resources are listable -- clients can discover all available files.

Configuration

The MCP server uses the same configuration as the main API server:

atlas.config.ts (if present)
Environment variables: ATLAS_DATASOURCE_URL, ATLAS_PROVIDER, provider API keys, etc.

See Environment Variables for the full reference.

Programmatic Usage

Create an MCP server instance in your own code:

import { createAtlasMcpServer } from "@atlas/mcp/server";

// Creates a fully configured MCP server with tools and resources registered
const server = await createAtlasMcpServer();
// Connect to any transport: server.connect(stdioTransport) or server.connect(sseTransport)

The server factory initializes configuration, registers tools and resources, and returns a ready-to-use McpServer instance. Connect it to any transport (stdio, SSE, or custom).

"ATLAS_DATASOURCE_URL is not set" -- The MCP server requires the same environment variables as the main API. Set them in your MCP client config's env block or ensure they're available in the shell.

Tools not appearing in Claude Desktop -- Restart Claude Desktop after changing claude_desktop_config.json. Check the cwd path points to your Atlas project root (where package.json and semantic/ live).

SSE connection refused -- The MCP server defaults to stdio, not SSE. Verify you started with --transport sse (e.g., bun packages/mcp/bin/serve.ts --transport sse). Check the port is not already in use (default 8080) and firewall rules allow the connection.

See Troubleshooting for general diagnostic steps.

Atlas MCP vs Raw Database MCP

Wondering why you'd use Atlas's MCP server instead of connecting Claude Desktop directly to your database with a tool like DBHub? Atlas's MCP server routes every query through the SQL validation pipeline and gives the AI your semantic layer for context — not just raw schema metadata. See Atlas vs Raw MCP for a full comparison.