Wake MCP server (wake-mcp)

wake-mcp is a small, read-only Model Context Protocol server that ships with Wake. It exposes Wake’s session index to any MCP client — Claude Code, Codex, Cursor, or anything else that speaks MCP over stdio — so an agent can search your history, list what you worked on recently, and read a past transcript page by page.

It covers everything Wake indexes: sessions from every supported agent on this machine, plus the local mirrors of any remote hosts you configured. Nothing here can modify a session. The server opens Wake’s index without write access, never scans or rebuilds it, and never touches the agents’ own files except to read a transcript.

Where it lives

Settings → Connect in Wake shows the exact path for your install with a copy button next to it, and one copy button per client (Show reveals the snippet before you copy it). wake-mcp setup prints the same snippets from a terminal. Updating Wake keeps the path, so there is nothing to redo after an update.

Setup

Claude Code

claude mcp add --scope user wake -- "/Applications/Wake.app/Contents/MacOS/wake-mcp"

Or install the Wake plugin instead, which adds this server and starts every new session knowing where your agents left off in the project (see Claude Code plugin):

claude plugin marketplace add iAmCorey/Wake --sparse .claude-plugin plugins/wake && claude plugin install wake@wake

Use one or the other, not both, or the tools are listed twice.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.wake]
command = "/Applications/Wake.app/Contents/MacOS/wake-mcp"

Or install the Wake plugin instead, which adds this server and starts every new session knowing where your agents left off in the project (see Codex plugin):

codex plugin marketplace add iAmCorey/Wake --sparse .agents/plugins --sparse plugins/wake && codex plugin add wake@wake

Use one or the other, not both, or the tools are listed twice.

Cursor

Merge into ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wake": { "command": "/Applications/Wake.app/Contents/MacOS/wake-mcp" }
  }
}

Any other client

Run the binary as a stdio MCP server with no arguments. It reads Wake’s index from the default location (~/Library/Application Support/wake/wake.db on macOS, ~/.local/share/wake/wake.db on Linux, %LOCALAPPDATA%\wake\wake.db on Windows); pass --db PATH to point it elsewhere.

If the index does not exist yet, the server exits with status 2 and a message on stderr asking you to launch Wake once — Wake builds the index on first run.

Removing it

claude mcp remove wake for Claude Code; for Codex and Cursor delete the wake block from the config file. Nothing else was installed.

Using it

Check that it is connected

• Claude Code: claude mcp list shows wake as connected; inside a session, /mcp lists the server and its five tools.
• Codex: restart Codex after editing config.toml; the wake_* tools show up in its tool list.
• Cursor: Settings → MCP shows wake with a green status dot.
• No client at hand: wake-mcp call wake_list_projects in a terminal prints exactly what an agent would see.

Just ask

You do not need new commands. Ask in plain language and the agent picks the tool:

Answers can cite wake://session/<key>#<seq> references; the seq numbers are the same ones Wake shows in its transcript view and search results.

Make the agent reach for it

Agents rarely call a tool nobody told them about. One line in the project’s CLAUDE.md, AGENTS.md or Cursor rules turns it into a habit:

Before asking me for context about this repository, check earlier sessions with the wake MCP tools:
wake_list_sessions with the current directory, then wake_get_session for the relevant one.

Claude Code and Codex can also be told where your agents left off in the project when a session starts — each recent session with its last question and reply — through a hook that runs wake-cli context; see Claude Code plugin and Codex plugin in the command-line guide. Both plugins bring this MCP server along.

A worked example

You:    What was I doing in this repo yesterday with Codex? I want to continue.

Agent:  [wake_list_sessions {"project": "/Users/me/Github/app", "agents": ["codex"], "since": "2d"}]
        [wake_get_session {"key": "codex:0195c2a1-…", "max_messages": 40}]

        Yesterday's Codex session (14:10–15:32) reworked the retry loop in sync.rs:
        it moved the backoff into `Retry::next_delay`, added the jitter test, and
        stopped at a failing assertion in `tests/sync.rs:88` (seq 61 in that session).
        Want me to start from that failing test?

Everything above happens locally; Wake itself does not change and the other agent’s files are only read.

What it does not do

• No write tools: nothing can delete, star, rename or resume a session. Resuming stays in Wake.
• Subagent transcripts that live inside a session (Claude Code sidechains, Cursor subagents) are not merged into the main transcript: wake_get_session lists their ids at the end and reads one when it is passed as subagent. Sub-agents that their agent records as sessions of their own (Codex spawn_agent, Grok) are folded under their parent in wake_list_sessions; the parent’s wake_get_session output lists them by key, and each reads like any other session.
• Antigravity conversations with no plain-text transcript on disk (older versions store the body encrypted) are metadata only, so an agent gets the same preview card Wake shows.
• Archived Codex sessions appear in search results but not in wake_list_sessions or wake_list_projects.
• Codex’s own background threads — the guardian auto-review, /review, compaction and memory consolidation that Codex writes into the same sessions directory — are not indexed at all: they never show up in search, lists or project counts, and there is no key to read them by. Threads started by spawn_agent are the exception: they are work the user asked for, so they are indexed under the session that spawned them, titled with the task name. The turns Codex copies from the parent when it forks a sub-agent are dropped, so the parent’s own conversation is only indexed once. After upgrading, rows an older Wake had indexed disappear once Wake itself has rescanned (launch it, or press Refresh); wake-mcp only reads the index and never rescans.

Keeping results fresh

Search and lists come from Wake’s index. Wake keeps the index current while it is running (file watching for JSONL-based agents; SQLite-based agents such as Copilot and OpenCode refresh on launch and on manual refresh); while the app is closed, a scheduled wake-cli refresh does the same pass (see docs/cli.md). Every reply ends with a line like

Index covers activity up to 2026-09-08 09:41:37 (local time); Wake keeps it fresh while it is running.

so an agent can tell how recent the data is. Two replies carry no freshness line: an unrecognised project, which returns early with the list of known projects, and an empty index, which says so instead. Reading a transcript with wake_get_session parses the agent’s own files rather than the index, so it does not depend on when Wake last scanned. Sessions mirrored from a remote host are read from their local mirror, so they are current as of the last successful sync.

Tools

All five tools are read-only and return Markdown text (content[0].text). Parameters are JSON; every parameter except the ones marked required is optional.

Shared parameters

wake_search

Full-text search across every indexed session: titles, user prompts, assistant replies, tool names and tool inputs (tool outputs are not indexed). A title match is reported as title and its reference points at the start of the session. Terms are ANDed. CJK text and code substrings such as useEffect( both work; terms shorter than three characters fall back to a slower substring scan.

Results are grouped by session, best matches first, with up to three snippets per session. Recently active sessions get a mild boost: an equally good match from last week outranks one from last year, but a clearly better match still wins regardless of age. Each snippet carries a reference of the form wake://session/<key>#<seq> that wake_get_session accepts directly. Archived sessions are included.

26 sessions match `二维码` (project /Users/me/Github/app) — showing 3, best matches first.

1. `claude-code:28ffac16-…` · Claude Code · "Session manager for coding agents"
  /Users/me/Github/app · updated 2026-08-14 19:45:47 · 524 messages · claude-opus-5
  - seq 209 (assistant, 2026-08-14 14:45:03): …search "**二维码**" 2>&1 |…
    ref: wake://session/claude-code:28ffac16-…#209

wake_list_sessions

Most recently updated sessions, newest first. Subagent sessions are folded into their parents and archived sessions are excluded. Pinned sessions are not moved to the top here (they are in Wake’s own list), so limit: 1 really is the newest session.

Each line shows the session key, agent, title, project, last update, message count, model, and badges such as @host (remote host), via vscode (source) or ★ starred.

wake_get_session

One transcript as compact Markdown, parsed live from the agent’s files.

The reply starts with a header (title, key, agent, host, project and branch, model, time range, message count), then one block per message:

### [seq 12] User · 2026-09-05 11:02:14
Why does the watcher drop events on Linux?

### [seq 13] Assistant · 2026-09-05 11:02:40
inotify queues overflow when …
- 🔧 Read: crates/wake-core/src/watcher.rs
- 🔧 Grep: need_rescan

Tool calls are folded to one line each (name plus input preview) unless include_tools is set; at most 40 tool calls are listed per message, the rest are counted. Injected context (system reminders, IDE context) is skipped and counted. Compaction summaries are kept as quotes. Images are noted, not included. Subagent transcripts (Claude Code sidechains, Cursor subagents) are listed at the end of the main transcript with their ids; pass one as subagent to read it, with the same paging options. The footer lists at most 30; subagent: "*" returns the full list without a transcript.

Child sessions (Codex spawn_agent sub-agents, Grok sub-sessions) are listed after it, by key — wake_list_sessions only returns roots, so the parent is where they are found. A child names its parent in the header line instead.

The footer says which seqs were shown and either End of transcript. or a from_seq=<n> hint for the next page. Seq numbers are the same ones Wake’s own search results and transcript view use.

If the key is unknown the tool returns an error result (isError: true) explaining what keys look like; if only a bare native id is given, the server looks it up and, when several hosts share that id, lists the candidates.

wake_list_projects

Projects (working directories) that have indexed sessions, most recently active first, with session counts and last-activity time. Archived-only projects are not listed.

wake_list_memories

The memory files coding agents keep for themselves on this machine, read-only: Claude Code’s per-project auto-memory (~/.claude/projects/<project>/memory/: MEMORY.md plus one file per topic) Codex’s memories (~/.codex/memories/*.md, user memory, and the per-session summaries in memories_1.sqlite) and ZCode’s per-project memory (~/.zcode/cli/memories/projects/<project>/memory/, the same MEMORY.md + topic-file layout; its project is recovered from the workspace hash in the directory name). Grouped by project, user memory (the notes that apply to every project, e.g. ~/.codex/memories/*.md) last; user memory is listed under any project filter because it applies everywhere (a project that matches no indexed project still lists it, with a note), and limit only caps the project memory — user memory is always appended. A memory file’s project is the one its sessions belong to, so a Claude Code memory whose sessions have all expired shows under Unknown project. Each entry ends with a wake://memory/<key> reference — pass it to wake_get_session to read the file (the file is read live from disk, so an agent’s latest edit shows). The instruction files you keep for agents are listed alongside: the global ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.codex/rules/*.rules, ~/.gemini/GEMINI.md, and — in every project Wake has sessions for — CLAUDE.md, CLAUDE.local.md, AGENTS.md, GEMINI.md, .cursor/rules/*.mdc, .cursorrules, .kiro/steering/*.md and .github/copilot-instructions.md. Which sources are read is configured in Settings → Memory locations. Wake never writes, edits or syncs these files.

wake_search also appends up to five memory files that mention the query, under Memory files that mention …, with the same references; project, agents and since apply to them too.

Session keys and references

• Local sessions: <agent>:<native id>, for example codex:0195c2a1-….
• Sessions mirrored from a remote host: <agent>:<host>:<native id>.
• References: wake://session/<key>#<seq> point at one message; wake_get_session accepts them as key and starts the page there.
• Memory files: wake://memory/<agent>:<path> (with a host segment for mirrored hosts); wake_get_session accepts them as key and returns the file.

The native id is the one the agent’s own --resume flag expects.

Errors

Command line

wake-mcp                       # serve MCP over stdio (what clients run)
wake-mcp --db PATH             # use another index database
wake-mcp setup                 # print the setup snippets for Claude Code / Codex / Cursor
wake-mcp call wake_search '{"query":"useEffect(","limit":3}'   # run one tool and print its text
wake-mcp --version

call is handy for checking what an agent would see. It exits non-zero when the tool reports an error.

Protocol details

• Transport: stdio, one JSON-RPC 2.0 message per line; logs go to stderr only.
• Methods: initialize, notifications/initialized, ping, tools/list, tools/call. No resources, prompts or sampling.
• Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 (the client’s requested version is echoed when it is one of these).
• Capabilities: tools only; every tool is annotated readOnlyHint: true.
• Several clients can each run their own wake-mcp at the same time; they are independent read-only processes over the same index.

Privacy and scope

• Everything runs on this machine. The server makes no network requests.
• Agents see the same session files Wake indexes — local agents’ data directories plus the local mirrors of any remote hosts you configured in Wake. Nothing leaves the machine.
• Wake’s read-only rules apply: other agents’ directories and databases are opened read-only and credential files are never read. The server writes nothing to the index; the one thing it can write is Wake’s own data directory, which resolving the default index path creates and, on a first run after the old vibex builds, migrates the old database into (--db skips that).
• An agent’s own session is indexed by Wake too, but its Wake lookups are not: tool calls to wake_* and shell runs of wake-cli / wake-mcp are left out of the search index, so searching a term tomorrow does not surface today’s search for it. Tool outputs are never indexed either.

See also

docs/cli.md — wake-cli, the same index from a shell, for agents that run commands rather than call tools. It prints the identical text.

Troubleshooting

• The client reports the server failed to start. Run the binary in a terminal: no Wake index at … — launch Wake once to build it means Wake has never run on this machine (or --db points to the wrong place). … is empty or from an older version means the index predates this Wake version; launching Wake once upgrades it, and so does wake-cli refresh.
• Results look stale. Keep Wake running, or schedule wake-cli refresh for the times it is closed (docs/cli.md); the freshness line at the end of every reply tells you what the index covers. Copilot / OpenCode / Antigravity / Hermes / OpenClaw databases refresh when Wake launches or when you click Refresh.
• A project path is not matched. Pass the absolute path of the repository, or its name. wake_list_projects shows the paths Wake knows.
• macOS refuses to run it (“cannot be opened because the developer cannot be verified”). Wake is signed but not notarized, and a client launching wake-mcp hits the same first-run gate as opening Wake itself. Clear the quarantine flag for the whole bundle once: xattr -dr com.apple.quarantine /Applications/Wake.app, then restart the client.