Skip to content

DocsUse

MCP clients and other editors

The entry each MCP client takes - Cursor, Gemini CLI, Claude Desktop, Devin Desktop, Zed, JetBrains AI Assistant, Codex CLI - written or printed by bbm-atlas mcp install and mcp config, or run with npx from the npm package.

Two commands

Every MCP client takes one of two things: a running server's /mcp endpoint, which shares the repositories you index with bbm-atlas serve, or a stdio server it starts itself. Each wants them in a shape of its own.

  • bbm-atlas mcp install --host <client> writes the client's project file, for the clients that have one: Claude Code's .mcp.json, Cursor's .cursor/mcp.json, VS Code's .vscode/mcp.json and Gemini CLI's .gemini/settings.json. It changes only BBM-Atlas's own entry, keeps a .bak of the file it replaces, and leaves a file with comments alone.
  • bbm-atlas mcp config --host <client> prints the entry for any client, for a file of your own or a settings page: the entry on standard output, where it goes on standard error.
terminal
bbm-atlas serve                                                    # the API, the console and /mcpbbm-atlas mcp install --host cursor --url http://127.0.0.1:8000/mcpbbm-atlas mcp config --host zed --url http://127.0.0.1:8000/mcp    # prints Zed's entry

Without --url, the entry starts a stdio server with the Python that ran the command. A client that starts its servers with npx can use the npm package instead. Connect your AI assistant covers Claude Code and VS Code, and Claude Code also has its own plugin.

With npx, from npm

A client that starts its servers with npx can run BBM-Atlas from `@byteblendmatrix/bbm-atlas`, the npm package, with nothing installed by hand but Node 20 or newer and Python 3.11 or newer. Its command, bbm-atlas-mcp, finds a Python with BBM-Atlas 1.0.0 or newer in it - --install installs or upgrades BBM-Atlas there with pip when it is missing or too old - and runs BBM-Atlas's MCP server on stdio:

terminal
{  "mcpServers": {    "bbm-atlas": {      "command": "npx",      "args": ["-y", "@byteblendmatrix/bbm-atlas", "--install"],      "env": { "BBM_ATLAS_STORAGE_BACKEND": "local" }    }  }}
  • mcpServers is the shape Claude Desktop, Cursor and Devin Desktop take; give the same command, arguments and environment in the shape your client takes.
  • BBM_ATLAS_STORAGE_BACKEND=local keeps the index between sessions; without it, the index lives in memory and each session indexes again. Only one process can open the local store: if bbm-atlas serve already runs with it, point the client at that server's /mcp instead.
  • --python PATH (or BBM_ATLAS_PYTHON) names the Python to use, and only that one. Its messages go to standard error: standard output is the MCP conversation.

Cursor

bbm-atlas mcp install --host cursor --url http://127.0.0.1:8000/mcp writes .cursor/mcp.json in the project. For every project, put the same entry in ~/.cursor/mcp.json:

.cursor/mcp.json
{  "mcpServers": {    "bbm-atlas": {      "url": "http://127.0.0.1:8000/mcp"    }  }}

Gemini CLI

bbm-atlas mcp install --host gemini --url http://127.0.0.1:8000/mcp adds the entry to .gemini/settings.json in the project, keeping your other settings. For every project, use ~/.gemini/settings.json:

.gemini/settings.json
{  "mcpServers": {    "bbm-atlas": {      "httpUrl": "http://127.0.0.1:8000/mcp"    }  }}

Claude Desktop

Claude Desktop starts a stdio server from claude_desktop_config.json: Settings → Developer → Edit Config opens it (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows). bbm-atlas mcp config --host claude-desktop prints the entry with your Python's full path:

claude_desktop_config.json
{  "mcpServers": {    "bbm-atlas": {      "command": "/path/to/python",      "args": ["-m", "bbm_atlas.cli", "mcp", "serve"]    }  }}

Devin Desktop (formerly Windsurf)

Devin Desktop reads mcp_config.json, which its MCP settings open (~/.config/devin/ on macOS and Linux, %APPDATA%\devin\ on Windows). bbm-atlas mcp config --host windsurf prints:

mcp_config.json
{  "mcpServers": {    "bbm-atlas": {      "serverUrl": "http://127.0.0.1:8000/mcp"    }  }}

Zed

Zed takes MCP servers under context_servers in its settings (zed: open settings). bbm-atlas mcp config --host zed prints the entry to merge in:

settings.json
{  "context_servers": {    "bbm-atlas": {      "url": "http://127.0.0.1:8000/mcp"    }  }}

JetBrains AI Assistant

In IntelliJ IDEA, PyCharm and the other JetBrains IDEs, open Settings → Tools → AI Assistant → Model Context Protocol (MCP), choose Add, and paste what bbm-atlas mcp config --host jetbrains prints:

terminal
{  "mcpServers": {    "bbm-atlas": {      "url": "http://127.0.0.1:8000/mcp"    }  }}

Codex CLI

Codex reads TOML: ~/.codex/config.toml, or .codex/config.toml in a trusted project. bbm-atlas mcp config --host codex prints:

config.toml
[mcp_servers.bbm-atlas]url = "http://127.0.0.1:8000/mcp"

Keys

A server on your own machine, started by bbm-atlas serve, needs no key. For one that does, add --api-key-env BBM_ATLAS_API_KEY: the entry refers to the variable, and the key is never written into a file.

ClientHow the entry sends the key
Claude CodeAuthorization: Bearer ${BBM_ATLAS_API_KEY}
Cursor, Devin DesktopAuthorization: Bearer ${env:BBM_ATLAS_API_KEY}
VS CodeA prompted input, ${input:bbm-atlas-api-key}: VS Code asks for the key once and keeps it in its secret storage
Codex CLIbearer_token_env_var = "BBM_ATLAS_API_KEY"
Gemini CLI, Zed, JetBrains AI AssistantRefused: their documentation gives no way to refer to a variable in a header

The VS Code extension in other editors

Cursor, VSCodium, Devin Desktop, Gitpod and Theia install the VS Code extension from Open VSX, where it is published as on the Marketplace. In Cursor, it registers BBM-Atlas's server with Cursor's own MCP API, so Cursor's agent gets the tools with nothing to configure.

Where the VS Code extension runs in an editor without VS Code's MCP provider API, BBM-Atlas: Copy MCP Configuration copies an entry in that editor's own format - Cursor's or Devin Desktop's, VS Code's otherwise - and says where it goes. The server the extension starts keeps its port from one session to the next, so the entry keeps working; bbmAtlas.server.port pins one.