Set up your agent (MCP)

Alkahest ships an MCP server in the CLI (alkahest mcp). 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.

Claude Code

npm install -g @cr8rcho/alkahest
claude mcp add alkahest -s project -- alkahest mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.alkahest]
command = "alkahest"
args = ["mcp"]

Any other MCP client works the same way — the server command is alkahest mcp.

Authentication

The MCP server needs a publish token for anything that touches the cloud (publishing, issues, notes). Either:

• run alkahest login --token alk_… once (the MCP server picks up the stored credential), or
• set ALKAHEST_TOKEN in the MCP server's environment (useful for per-project configs).

Create tokens at alkahest.app → Publish tokens. Local-only tools (scan, the map readers) work without a token.

What your agent can do

Area	Tools
Code map	scan, publish, overview, get_screen, who_calls, set_summary, set_prd
Issues	issues, add_issue, update_issue, link_issues, map_issue, complete_issue
Decisions	ask_issue, reply_issue, issue_comments, resolve_issue_question
Notes	notes, add_note, get_note, update_note, link_notes, map_note
Comments	comments, add_comment, reply_comment, resolve_comment, comment_to_issue
Meta	list_projects, maps, create_map, history, 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.

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.