atlas-mcp

atlas-mcp

Connect any AI coding agent (Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, Windsurf, VS Code/Copilot, Cline…) to your team'sAtlas knowledge hub. The agent pulls your approved prompts, docs and scoped secrets as context —and Atlas passively captures what the AI builds, so the team can see it without anyone using Jira.

Install globally (once per machine)

bun install -g github:Nara-Virtual/atlas-mcp#main
# or: npm install -g github:Nara-Virtual/atlas-mcp#main

This puts atlas on your PATH — repo setup, hooks, and the stdio MCP server IDEs spawn.

Update to latest

atlas update
# or without a prior global install:
npx -y github:Nara-Virtual/atlas-mcp#main update

Pulls the latest commit from GitHub main (IDE npx configs from atlas install already use #main).

One-command install into your AI clients

atlas install --key atlas_mcp_… --project Nara     # every client below that you use
atlas install --key atlas_mcp_… --only codex,gemini # just those
atlas uninstall [--only cursor]                      # take atlas out again (other servers stay)
atlas doctor                                         # check key, connection, tools, prompts, wired clients

Cursor, Claude Code, Claude Desktop, Windsurf, VS Code (+ Insiders), GitHub Copilot CLI, Codex CLI(~/.codex/config.toml) and Gemini CLI (~/.gemini/settings.json). Claude Desktop and Codex take the keyliterally (they cannot read your shell profile), so they need --key; the others use ${ATLAS_MCP_KEY}.A config file that is not plain JSON (comments, a typo) is skipped and never rewritten; the first change to anyfile leaves a one-time <file>.atlas-bak copy. Zed and Cline keep JSONC settings — add the stdio entry by hand(command: npx, args: ["-y", "github:Nara-Virtual/atlas-mcp#main"], env: ATLAS_MCP_KEY, ATLAS_BASE_URL).

One-command setup

# in your repo root — uses folder name as project; creates if missing
atlas .
# or pin a specific Atlas project by name:
atlas . --project Conference

Requires ATLAS_MCP_KEY in your environment (or pass --key). If the project exists, you get linked immediately; if not, Atlas asks to create it.

Then create an MCP key in Atlas → Settings → API keys → MCP key (pick toolsets, read-only, expiry),and export it:

export ATLAS_MCP_KEY=atlas_mcp_xxxxxxxx      # add to your shell profile
export ATLAS_BASE_URL=https://atlas.naravirtual.in

Claude Code only — capture every prompt + session automatically (zero agent cooperation):

atlas hooks install

Env files and logs from the terminal

Needs ATLAS_API_KEY with secrets:read, secrets:reveal, secrets:write (and logs:write for atlas log).The project comes from .atlas / ~/.atlas/config.json, ATLAS_PROJECT or --project.

atlas env pull production -o .env      # exact file (comments, order, quotes kept); remembers v<N>
atlas env diff                         # + added  ~ changed  - removed keys — values never printed
atlas env push -m "rotate stripe key"  # shows the diff, asks, pushes as v<N+1>; rejected if Atlas moved on
atlas env watch --yes                  # push on every save (without --yes it asks each time)
atlas env run --file production -- bun start   # env injected into the process, never written to disk
bun start 2>&1 | atlas log --source api --level info   # tees stdin and ships lines to Atlas logs

Base versions live in .atlas.env.json (paths and version numbers only — add it to .gitignore).A push whose base is stale gets a 409: pull, merge, push again. Nothing is ever overwritten silently.

Sync docs, prompts and code from a local folder

Needs ATLAS_API_KEY with docs, prompts and code read + write (only the kinds your mappings use).

atlas sync init --project Nara     # writes .atlas.sync.json with mappings detected from this folder
atlas sync status                  # + new  ↑ changed here  ↓ changed in Atlas  ! conflict  - deleted on one side
atlas sync push                    # shows the plan, asks, pushes (--yes to skip the question, --dry-run to only look)
atlas sync pull                    # same, the other way
atlas sync push --delete           # also delete in Atlas what you deleted here (pull --delete: the reverse)
atlas sync push --ours docs/a.md   # conflict: keep the local file   (--theirs <path> takes Atlas's; bare flag = all)
atlas sync watch --yes             # push on every save (debounced); conflicts are reported, never overwritten

.atlas.sync.json (commit it):

{
  "project": "Nara",
  "mappings": {
    "prompts/**/*.{md,txt}": "prompts",
    "docs/**/*.md": "docs",
    "src/**/*.{ts,tsx,py,sh,sql}": "code"
  },
  "maxBytes": 262144,
  "ignore": ["docs/drafts/**"]
}

• The first matching glob wins, so list prompts before a broad **/*.md. .gitignored files, binariesand files over maxBytes are never synced.
• Markdown → a doc: the title is the first # heading (or the file name), folders become parent pages.Prompt files → prompts (same title rule). Code files keep their path.
• .atlas.sync-state.json (gitignored automatically) remembers each file's content hash and the Atlasrevision it was last in sync at, so status can tell "changed here", "changed in Atlas" and "both".Atlas also remembers which path each item came from, so a teammate's fresh clone lines up.
• Every push and pull is audited in Atlas as sync.pushed / sync.pulled (counts only).

What it exposes (scope-gated — tools you can't use are hidden)

The tool catalog comes from the server on every connect (titles and read-only / destructive annotations included), soit always matches your key's toolsets:

• context: atlas_browse (any surface), atlas_read (any item; images are shown to the agent), atlas_search, atlas_context, atlas_get_secret.
• write: atlas_write (docs, code, prompts, comments, scripts, images…; stdio supports localPath).
• capture: atlas_log_work, atlas_save_prompt.
• tasks: atlas_my_tasks, atlas_list_tasks (a task with its images), atlas_get_image, atlas_create_task, atlas_update_task, atlas_comment_task.
• ops: atlas_uptime, atlas_logs, atlas_databases, atlas_deployments, atlas_server_usage, atlas_dokploy_api_search, atlas_dokploy_api_call (reads); deploy: atlas_deploy_action, atlas_dokploy_api_call (operate / configure; destroy and instance-wide with "Allow Dokploy admin").
• inbox / team / mynotes / chat: through atlas_browse / atlas_read / atlas_write, plus atlas_chat_send.

MCP prompts (work_on_task, my_day, ops_check, your team's Prompt library), resources (atlas://task|doc|code|image/{id}),resource templates and completions are forwarded to the remote endpoint (<atlas>/api/mcp) with your key, so astdio-only client has the same surface as a URL config. The tool list is re-read every 5 minutes: a server deployadds or changes tools in an open session without restarting the IDE, and an IDE opened offline starts from the lastcopy of the manifest.

How it works

Calls time out after 30 s; reads retry once on a network failure or a 5xx, writes never repeat. Errors say what to do("key revoked → create a new MCP key", "rate limited — retry in 12 s").

A thin, cached client over the Atlas REST API. Reads are served from a local cache(~/.atlas/cache, stale-while-revalidate) so they're instant and work offline; writes queue and flushwhen the network returns. All auth, fine-grained scopes and audit are enforced server-side.

The .atlas file binds the repo to an Atlas project and selects toolsets:

{ "project": "general", "autoCapture": true, "toolsets": ["context","capture","tasks"], "readOnly": false }

The key (secret) is never in .atlas — it lives in your IDE env / shell profile.

Agent transport options

Repo: https://github.com/Nara-Virtual/atlas-mcp

Remote (zero local install beyond the key) — point any client at the hosted server:

claude mcp add --transport http atlas https://atlas.naravirtual.in/api/mcp --header "Authorization: Bearer $ATLAS_MCP_KEY"

Or for Cursor/Windsurf/VS Code, paste the remote config (see Atlas → Connect agent for your exact snippet).

Local (repo-aware, recommended for capture) — stdio via globally installed atlas (reads .atlas, offline cache):

atlas .                              # set up a repo
# agents are configured to run:  atlas

Auth is read from ATLAS_MCP_KEY (set once in your shell profile). Default endpoint ishttps://atlas.naravirtual.in; override with ATLAS_BASE_URL.