retrievr

Guide

Add document search to Codex

After this, Codex can answer from your own documents and quote the page it read. The entry is TOML, not JSON — that is the part worth reading twice.

1. Give Codex the tool

Paste this into a session and let it work:

Fetch https://retrievr.io/install and follow it.

It takes you through approving a sign-in, writes the key to ~/.config/retrievr/credentials without printing it, and downloads the MCP server to ~/.config/retrievr/mcp.mjs.

2. Add the entry to ~/.codex/config.toml

Codex keeps its configuration in TOML. A mcpServers block is not read here; the entry is a table under mcp_servers:

[mcp_servers.retrievr]
command = "node"
args = ["/home/you/.config/retrievr/mcp.mjs"]

Write the absolute path. Nothing expands ~ on this route — not the shell, because there is no shell, and not Codex — so a tilde in args points at a directory named ~ that does not exist. echo $HOME prints the prefix to use.

The shape is checked against Codex’s own configuration reference, which is the page to trust if this guide and your version disagree.

3. Check it loaded

Start a new session — the tool list is read when one starts, so a session already open will not see it — then ask Codex what tools it has. retrievr should be there with five: retrievr_search, retrievr_documents, retrievr_upload, retrievr_upload_status and retrievr_delete_document.

Nothing there means the file did not parse or the section name is wrong. A TOML error is usually a missing bracket rather than a missing key.

4. Ask it something

Add a document from your library — the first five need no payment — then ask in plain language:

In the lease, what does it say about termination?
Which of my documents mentions the notice period?

Every passage comes back with its page, character range and licence, so the answer can be checked against the page rather than taken on trust. The service is always ready: a query is answered in well under a second.

When the tool does not appear

Three causes, in the order they happen. The session was already open, so the tool list was read before the file changed. The table is nested under another table — in TOML, [mcp_servers.retrievr] must sit at the top level, and a duplicate header above it silently moves every key below into the wrong parent. Or the path in args still has a ~ in it, which nothing expands here.

A TOML file that fails to parse usually makes Codex ignore the whole file rather than the one section, so an unrelated setting disappearing is a strong signal to look for a missing bracket rather than at this entry.

What it costs

$0.01 per query, charged when the query is accepted. Uploading and indexing are free. The full price list, or the same guide for Claude Code or opencode.