@atlas/mcp#

MCP (Model Context Protocol) server exposing Atlas app internals as tools for AI/LLM debugging.

Architecture#

JSON-RPC over stdio with Content-Length framing (like LSP). No external dependencies.

Key Exports#

createMcpServer(tools, ctx) — creates an MCP server with stdin/stdout transport
createContext(opts?) — builds an AtlasMcpContext from optional service references
collectTools(ctx) — returns tools based on what services are available in context
defineTool(tool) — identity helper for defining a tool with type safety

AtlasMcpContext#

Holds optional references: db, cache, routes, config, storage, migrationsDir, logBuffer. Tools auto-register based on which fields are present.

Built-in Tools#

Tool	Requires	Description
`db.query`	db	Execute SQL, returns rows as JSON
`db.schemas`	db	List tables and columns
`migrate.status`	db + migrationsDir	Show applied/pending migrations
`migrate.up`	db + migrationsDir	Run pending migrations
`migrate.down`	db + migrationsDir	Rollback last migration
`cache.get`	cache	Get value by key
`cache.set`	cache	Set value with optional TTL
`cache.del`	cache	Delete a key
`cache.flush`	cache	Flush all entries
`routes.list`	routes	List HTTP routes
`config.show`	config	Show config (secrets redacted)
`storage.list`	storage	List files with optional prefix
`storage.presign`	storage	Generate presigned URL
`health.check`	(always)	Check service connectivity
`docs.list`	(always)	List every package reference, guide including `docs/agents.md`, and root documentation entry point
`docs.read`	(always)	Read one package, guide, or root documentation source
`logs.tail`	logBuffer	Get recent log lines

The docs.* tools are always present so an agent connected to an Atlas-built app can self-introspect the framework — no web fetch required.

Usage#

Programmatic#

import { createContext, collectTools, createMcpServer } from "@atlas/mcp"

const ctx = createContext({ db, cache, routes })
const tools = collectTools(ctx)
const server = createMcpServer(tools, ctx)
await server.start()

CLI#

atlas mcp

Or directly:

bun run packages/mcp/entry.ts

Environment variables: DATABASE_URL, DATABASE_PATH, REDIS_URL, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION.

Types#

McpServer = { start(): Promise<void>; stop(): void }
AtlasMcpContext = { db?, cache?, routes?, config?, storage?, migrationsDir?, logBuffer? }
Tool = { name; description; inputSchema; handler(input, ctx) → Promise<unknown> }
ToolInput — JSON-schema-shaped input descriptor

Dependencies#

Sibling packages are optional — pass only the services you want exposed:

@atlas/db — enables db.* and migrate.* tools
@atlas/cache — enables cache.* tools
@atlas/server — enables routes.list
@atlas/config — enables config.show (secrets redacted)
@atlas/storage — enables storage.* tools
@atlas/migrate — enables migrate.up / migrate.down

External: none. Pure JSON-RPC over stdio with Content-Length framing.

Testing#

bun test packages/mcp/