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.jsonand Gemini CLI's.gemini/settings.json. It changes only BBM-Atlas's own entry, keeps a.bakof 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.
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 entryWithout --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:
{ "mcpServers": { "bbm-atlas": { "command": "npx", "args": ["-y", "@byteblendmatrix/bbm-atlas", "--install"], "env": { "BBM_ATLAS_STORAGE_BACKEND": "local" } } }}mcpServersis 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=localkeeps the index between sessions; without it, the index lives in memory and each session indexes again. Only one process can open the local store: ifbbm-atlas servealready runs with it, point the client at that server's/mcpinstead.--python PATH(orBBM_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:
{ "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:
{ "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:
{ "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:
{ "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:
{ "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:
{ "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:
[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.
| Client | How the entry sends the key |
|---|---|
| Claude Code | Authorization: Bearer ${BBM_ATLAS_API_KEY} |
| Cursor, Devin Desktop | Authorization: Bearer ${env:BBM_ATLAS_API_KEY} |
| VS Code | A prompted input, ${input:bbm-atlas-api-key}: VS Code asks for the key once and keeps it in its secret storage |
| Codex CLI | bearer_token_env_var = "BBM_ATLAS_API_KEY" |
| Gemini CLI, Zed, JetBrains AI Assistant | Refused: 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.