Guide
Add document search to opencode
After this, opencode can answer from your own documents and quote the page it read. The entry nests under mcp, and the command is an array — those are the two differences that matter.
1. Give opencode the tool
Paste this into a session and let it work:
Fetch https://retrievr.io/install and follow it.Approve the sign-in when it asks. The key lands in ~/.config/retrievr/credentials and is never printed, and the MCP server lands in ~/.config/retrievr/mcp.mjs — that is the path the entry below points at.
2. Add the entry to opencode.jsonc
opencode keeps MCP servers under the mcp key, not mcpServers, and command is a list rather than a string:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"retrievr": {
"type": "local",
"command": ["node", "/home/you/.config/retrievr/mcp.mjs"],
"enabled": true
}
}
}type: “local” says this is a process on your machine, which is why it takes a command at all. enabled: true is what makes opencode start it — a server that is defined and not enabled looks exactly like one that is missing, which is the failure worth knowing in advance.
The path is absolute for a reason: an array of arguments reaches the process without a shell, so ~ is never expanded. echo $HOME prints the prefix.
The shape is checked against opencode’s MCP documentation.
3. Check it loaded
Restart opencode. The tool list is read when a session starts, so a running session will not pick the entry up. Then ask for the available tools: retrievr should be there with five — retrievr_search, retrievr_documents, retrievr_upload, retrievr_upload_status and retrievr_delete_document.
4. Ask it something
Put a document in your library — the first five are free — then ask:
In the contract, what does it say about the notice period?
Which of my documents mentions the budget?Passages come back with their page, character range and licence. The service is always ready: a query is answered in well under a second, and there is nothing to start on your side.
When the tool does not appear
Check enabled first. A server defined without "enabled": true is loaded and never started, which produces exactly the same result as a server that was never written. Then check that the block is under mcp and not mcpServers — the key is different from every other JSON client, and the wrong one is not an error, it is an ignored key.
If command was pasted as a string instead of an array, opencode sees a program whose name contains spaces and starts nothing.
What it costs
$0.01 per query, charged when the query is accepted, and uploading is free. The full price list, or the same guide for Codex or Hermes.