Connect Codex in your IDE to Earkeep

Every time Earkeep opens, it puts the command at ~/.local/bin/earkeep-mcp, pointing into the app. Codex launches it when it needs it and talks to it over standard input and output. The command reads your transcript files straight from disk, so it works whether or not Earkeep is running, and it opens no port: there is no address at which anything off your device could reach it.

It offers two tools, and both are read-only. Nothing connected here can create, edit or delete a meeting.

• search_spans finds saved meetings by a case-insensitive match on their title or notes, or lists all of them when you don't give it a query. Newest first, twenty at a time.
• read_span takes one meeting's id and returns that meeting plus the transcript lines it covers.

Worth knowing before you write a prompt: search matches titles and notes, not the words inside transcripts.

Open Earkeep once, so the command is in place. The extension reads the same config.toml the command line uses. Open it from the gear icon, then Codex Settings, then config.toml, and add:

Replace you with your username. The path has to be absolute, because this file does not expand ~. Easier still: open Settings → MCP in Earkeep, which gives you this same block with your own path already in it, ready to copy.

Reload the Codex extension after saving. It reads the file when it starts, so the entry does nothing until it does.

Or over HTTP. Earkeep also serves the same tools at a loopback address while the app is running. Use this entry instead if you would rather connect by URL; the port is the default, and Settings → MCP shows the real one:

Already added it in the terminal? Then it is already here. The two share this file, so the one command on the CLI page writes the same entry and you can skip this page entirely.

With the extension reloaded, ask Codex for something only Earkeep can answer:

"Use the earkeep tools to find the last meeting about this project and turn what was decided into a checklist."

Real titles from your own week mean the connection is live. If you have the command line to hand, codex mcp list reads the same configuration and is the quickest way to confirm the entry parsed.

Nothing appears. Two things in order: the TOML has to be valid, and the extension has to have been reloaded since you saved.

The section header is wrong. It is [mcp_servers.earkeep], with an underscore and a plural. A near-miss parses as an unrelated setting and is ignored without complaint.

The server fails to start. The path is wrong or the command is missing. Check it in a terminal:

If nothing is there, open Earkeep once and it puts the command in place. If it is there, compare the path in your config with the one in Settings → MCP: a ~, or a username that isn't yours, is the usual mistake. If something else is at that path, Earkeep leaves it alone rather than overwrite a file you put there; move it aside and open Earkeep again, or set command = "/Applications/Earkeep.app/Contents/MacOS/earkeep" with args = ["mcp"].

You connected over HTTP and it fails. That route needs Earkeep running, and the port in Settings → MCP has to match. A port change takes effect when Earkeep restarts.

It connects but finds nothing. The server searches saved meetings, so a day that was captured but never had a span kept from it has nothing to find.

• Connect Codex CLI: the same server in one command, writing this same file.
• Set up Codex as an in-app agent: the other direction, where Codex runs inside Earkeep beside the meeting.
• Agents and MCP: why both exist and what each is for.
• All Earkeep how-tos.