Set up your agent (MCP) — Alkahest Docs

Connect Claude Code, Codex, or any MCP client — beside your checkout via the CLI, or from anywhere with no install.

Alkahest ships an MCP server. Register it once and your agent can scan, publish, file and update issues, take notes, and — most importantly — ask you questions when it hits a decision it shouldn't make alone.

The same server runs in two places: beside your checkout (the CLI's alkahest mcp) and hosted (a URL, no install). Which one you register decides what your agent can do — pick in step 2.

1. Get a token

Publishing, issues and notes go through your account, so they need a API token. Create one at alkahest.app → API tokens — it starts with alk_ and is shown once.

That page prints every snippet below with your token already in it, so you can copy and paste straight from there. The versions here use alk_… as a placeholder.

The form asks what the token is for. Full access is the one this page needs. The other kind, Task capture, can only create tasks and is meant for a phone shortcut — see Capture from your phone.

(Scanning and reading local maps need no token — skip this if that's all you want.)

2. Pick your path

One decision: does the server run in a repo, or from anywhere?

	In a repo	From anywhere
What it is	The CLI's `alkahest mcp`, running beside your source tree	The same server, hosted — a URL you paste
Install	`npm install -g @cr8rcho/alkahest`	nothing
Code maps	`scan` + `publish` the folder you're standing in	reads the published map (`overview`, `get_screen`, `who_calls`)
Which project	inferred from the checkout	name it — pass `project` (a slug from `list_projects`)
Everything else	issues, notes, tasks, decisions, search	exactly the same

The difference isn't the client — it's the folder. The hosted server has no source tree to stand in, so the six tools that need one (scan, publish, set_summary, set_prd, check_version, comment_to_issue) don't exist there, and the project must be named because no checkout can imply it. Everything that never needed a folder — issues, notes, tasks, the decision loop, search — works identically on both.

In a repo is the path for coding agents working on a checkout — it's the only way to scan and publish. Install the CLI first:

npm install -g @cr8rcho/alkahest

From anywhere is the path when there's no checkout in play — claude.ai on the web or your phone, a machine you can't install on, or a project that isn't code at all (a wiki, a notebook, an issue backlog). Your connector URL is your full-access token appended to the endpoint:

https://www.alkahest.app/api/mcp/alk_…

Use the www host — the apex domain answers with a redirect some MCP clients won't follow. And treat the URL like the token it contains: anyone holding it can act as you; revoking the token at API tokens kills it.

3. Register the server

Pick your client. Each section shows both paths where both apply.

Claude Code

In a repo — run this in your project; it registers the server for this machine:

claude mcp add alkahest -e ALKAHEST_TOKEN=alk_… -- alkahest mcp

Or write the file yourself — .mcp.json at your project root, the same shape Cursor uses:

{
  "mcpServers": {
    "alkahest": {
      "command": "alkahest",
      "args": ["mcp"],
      "env": { "ALKAHEST_TOKEN": "${ALKAHEST_TOKEN}" }
    }
  }
}

This is the file -s project would have written, and it's meant to be committed — so it reads the token from your shell environment rather than carrying it. Claude Code expands ${VAR} (and ${VAR:-default}) when it starts the server, so each teammate exports their own ALKAHEST_TOKEN. Claude Code asks for approval the first time it sees a project-scoped server. Keeping the file out of git? Then put the token inline, exactly as in the Cursor snippet below.

From anywhere — one command, no CLI install:

claude mcp add --transport http alkahest https://www.alkahest.app/api/mcp/alk_…

claude mcp list confirms it connects either way.

Claude Desktop

In a repo — add to claude_desktop_config.json (Settings → Developer → Edit Config; on macOS it's ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json), then restart the app:

{
  "mcpServers": {
    "alkahest": {
      "command": "alkahest",
      "args": ["mcp"],
      "env": { "ALKAHEST_TOKEN": "alk_…" }
    }
  }
}

Desktop launches servers with a minimal PATH, so a version-managed install (nvm, asdf) may not resolve alkahest — if the server won't start, put the absolute path from which alkahest in command.

From anywhere — three options:

Desktop extension (one-click): download alkahest.mcpb, double-click it (or drag it onto Settings → Extensions), and paste your alk_ token into the install form — it's stored in your OS keychain, and Desktop's bundled Node runs the extension, so nothing else is needed. The bundle is a thin relay onto the hosted server: new tools appear without reinstalling.
Custom connector: the desktop app uses the same account-level connector as the web and your phone. Add it once in Settings → Connectors — the Claude on the web & mobile steps below cover it. Pick this over the extension when you want one registration to cover your phone too.
Keep it in the config file: claude_desktop_config.json only takes command servers, so put the URL behind the mcp-remote bridge — no Alkahest CLI needed, just Node:

{
  "mcpServers": {
    "alkahest": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.alkahest.app/api/mcp/alk_…"]
    }
  }
}

The bridge relays stdio↔HTTP; this machine-local entry is the choice when you don't want the connector on your whole account, or the account is a company workspace that vetoes custom connectors.

Codex

Add to ~/.codex/config.toml — in a repo:

[mcp_servers.alkahest]
command = "alkahest"
args = ["mcp"]
env = { ALKAHEST_TOKEN = "alk_…" }

From anywhere — a url key means a Streamable HTTP server; the token is already in the URL, so that's the whole entry:

[mcp_servers.alkahest]
url = "https://www.alkahest.app/api/mcp/alk_…"

Cursor

Add to ~/.cursor/mcp.json — or .cursor/mcp.json for one project. In a repo:

{
  "mcpServers": {
    "alkahest": {
      "command": "alkahest",
      "args": ["mcp"],
      "env": { "ALKAHEST_TOKEN": "alk_…" }
    }
  }
}

From anywhere:

{
  "mcpServers": {
    "alkahest": {
      "url": "https://www.alkahest.app/api/mcp/alk_…"
    }
  }
}

Claude on the web & mobile

The claude.ai apps (your phone and the desktop app included) take the from-anywhere URL as a custom connector — one registration is account-level and covers them all:

In Claude, open Settings → Connectors → Add custom connector (on the claude.ai website — the mobile app hands connector setup to the browser; adding it once covers web and phone).
Name: alkahest (anything you like). Remote MCP server URL: your connector URL from step 2. Leave the OAuth fields under Advanced settings empty — the token in the URL is the credential. Then Add.
In a chat, open the tools (🔧 / paperclip) menu and make sure the alkahest connector is enabled. Ask something like "list my alkahest projects" — a list_projects call coming back with your projects means it's wired up.

On a company Claude workspace (Team/Enterprise), adding custom connectors may be disabled by your org's admin — if the Add button is missing or rejected, that's the policy, not the URL. Ask the admin to allow it, use a personal Claude account, or fall back to the in-a-repo server.

Any other MCP client

Both paths carry over to every client:

In a repo: the server command is alkahest mcp, and the token is ALKAHEST_TOKEN in that server's environment (the field is usually called env, environment, or "Environment variables"). No global install? npx -y @cr8rcho/alkahest mcp runs the same server.
From anywhere: any client that speaks Streamable HTTP takes the URL as-is — no headers, no OAuth.

Most clients accept the same JSON as Cursor — but the file location and the exact shape are the client's own, so check its MCP docs rather than assuming the snippets above drop in.

No config file? Log in instead

On the in-a-repo path there's a third option:

alkahest login --token alk_…

That saves the credential to your home directory and every agent on this machine picks it up — the same login the CLI uses, so one token covers both.

If you do both, the saved login wins. The token resolves in the order explicit argument → saved login → ALKAHEST_TOKEN, so a stale alkahest login quietly overrides the token in your MCP config. alkahest status shows which token is actually in play and where it came from; alkahest login --token alk_… switches it, and alkahest logout drops the saved one so ALKAHEST_TOKEN takes over again.

4. Which project the tools write to

Only the code map comes from a folder. Notes, issues, tasks and maps are addressed by project slug, so your agent can write to a project the current directory knows nothing about — one that was never published, or lives in another repo entirely. Every such tool takes a project parameter:

notes / add_note / issues / add_issue / list_tasks / maps / create_map / search / …
  → project: "my-wiki-2772c2"      # a slug from the list_projects tool

alkahest publish binds a checkout to a project (it writes .alkahest/project.json), and inside such a folder the parameter is redundant — the tools already know where they are. On the from-anywhere path there is no folder, so tools answer no_slug until you pass project — telling Claude once per conversation, or pinning it in a Claude Skill / project instruction, covers the rest.

Pin one server to one project. Keeping a personal wiki, or a notebook you write to from anywhere? Name it once in the server's environment and drop the parameter for good:

{
  "mcpServers": {
    "alkahest": {
      "command": "alkahest",
      "args": ["mcp"],
      "env": { "ALKAHEST_TOKEN": "alk_…", "ALKAHEST_PROJECT": "my-wiki-2772c2" }
    }
  }
}

The project resolves in the order explicit project argument → linked checkout → saved login → ALKAHEST_PROJECT. The env var is deliberately last: a wiki-configured server still defers to a real linked checkout, so it won't hijack the code project you're standing in.

On the CLI the same address is --slug <slug>; alkahest projects lists them.

What your agent can do

Area	Tools
Find	`search` — one query across notes, issues and tasks, before creating anything
Code map	`overview`, `get_screen`, `who_calls` — plus, in a repo only: `scan`, `publish`, `set_summary`, `set_prd`
Issues	`issues`, `add_issue`, `update_issue`, `link_issues`, `map_issue`, `complete_issue`
Tasks	`list_tasks`, `add_task`, `update_task`, `complete_task`
Decisions	`ask_issue`, `reply_issue`, `issue_comments`, `resolve_issue_question` — and the task twins `ask_task`, `reply_task`, `task_comments`, `resolve_task_comment`
Notes	`notes`, `add_note`, `get_note`, `update_note`, `note_props`, `link_notes`, `map_note`
Comments	`comments`, `add_comment`, `reply_comment`, `resolve_comment` — plus, in a repo only: `comment_to_issue`
Meta	`list_projects`, `maps`, `create_map`, `history`, `presets` — plus, in a repo only: `check_version`

The issues tool marks each issue as actionable or not — done, blocked-by, and awaiting decision are all derived — so an agent can pick its next task without guessing. When it needs you, it calls ask_issue and the issue stops being actionable until you answer. See Issue maps & decisions.

First thing to say

Once the tools are there, your agent can set up a documentation workflow on its own:

Use the alkahest MCP presets tool to set up the as-built docs preset in this repo — install whatever is missing, then do the first documentation pass and mirror it.

presets hands it the packaged convention — the writing skills, the note maps, a docs/ scaffold and a reference sync script. It installs the skills you don't already have (yours are never overwritten), writes the repo files, and keeps going until the first documents are on a map. The CLI equivalent is alkahest docs init. See Mirror a docs folder.

One-prompt setup

Don't want to do any of this by hand? Paste the Quickstart prompt into your agent — it installs the CLI, registers MCP, scans, and opens the map for you.