Oko MCP server
Commit Oct 22, 2026Enables coding agents to perform ranked code searches with exact excerpts and line numbers to reduce token usage and tool calls.
Also known as bartlomein/oko
- Stars
- 14
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.9.1
- Last commit
- Oct 22, 2026
- License
- MIT
What is Oko MCP?
Oko enables coding agents to perform ranked code searches with exact excerpts and line numbers to reduce token usage and tool calls.
Summary generated from the project's README
About Oko MCP server
Helping coding agents find relevant source code faster is what Oko does for developers using AI-driven editors. By providing ranked code searches with exact excerpts and line numbers, it reduces the number of tokens and tool calls an agent needs to complete a task. This tool works locally on macOS and Linux, ensuring that search operations run on your machine while only specific questions and snippets are sent to the Jev relevance model for ranking.
To use Oko, you run the setup command for your specific client, such as Claude Code, Codex, Cursor, OpenCode, or Pi. The setup process requires a TypeSafe AI key for the ranking feature, though a no-key mode is available for local keyword ranking only. Once configured, it integrates directly into your existing workflow, allowing agents to skip unnecessary file reading and focus on the correct code immediately.
What you can do with it
- 1Reduce agent token consumptionA developer can use Oko to ensure their coding agent spends 33–44% fewer tokens during a session.
- 2Minimize unnecessary tool callsYou can hand a complex coding task to an AI client to reduce the number of tool calls by up to 89%.
- 3Speed up coding agent sessionsAn engineer can accelerate the time it takes for agents like Claude Code or Pi to finish tasks.
- 4Locate specific code logicYou can ask the terminal where specific logic is handled to get ranked results.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
TYPESAFE_API_KEYRequiredSecretTypeSafe AI key for ranking with Jev.
| Name | Description | |
|---|---|---|
| TYPESAFE_API_KEY | TypeSafe AI key for ranking with Jev. | RequiredSecret |
Automated checks
Ran Nov 12, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubOko gives Claude Code, Codex, Cursor, OpenCode and Pi a better code search. When you ask your agent about your code, Oko has already found the relevant source, so the agent spends fewer rounds searching and reading files it does not need.
- Faster: about half the time in Claude Code, OpenCode and Pi; a quarter less in Codex.
- Cheaper: 33–44% fewer tokens with every tool we measured.
- Fewer detours: 65–89% fewer tool calls.
- Better ranking: puts the right file first more often than any published method on Agent Retrieval Bench.
- Local first: search runs on your machine; only the question and selected snippets go to the ranker (privacy).
Quick start
brew install bartlomein/tap/oko
cd your-project
oko setup --client claude # or codex, cursor, opencode, pi, all
Without Homebrew: curl -fsSL https://raw.githubusercontent.com/bartlomein/oko/main/install.sh | sh.
Then use your coding tool as usual. Setup asks for a TypeSafe AI
key the first time, connects your tool to Oko for this project, and checks the
connection. Run it once per project; oko upgrade keeps everything current
(with Homebrew, run brew upgrade oko first).
The first time you open the project, Codex shows Hooks need review. Choose
Trust all and continue. If you skipped it, /hooks brings it back.
Cursor adds a project's tools switched off. Open Customize > MCPs, click oko and turn it on.
Pi 1.0 or later. Trust the project when Pi asks, then check /mcp.
Pi setup.
Start a new session after setup.
macOS (Apple Silicon and Intel) and Linux (ARM64 and x64, glibc 2.35+). The
installer puts oko in ~/.local/bin; add it to your PATH if needed.
Other install options · Connect a tool by hand ·
Keys and configuration. For search without a key,
add --no-jev: local keyword ranking only.
Results
The same task given to the same coding tool twice, once with its own search and once with Oko, in the same run. Means per session.
| Coding tool | Time | Tokens | Tool calls | Tasks passed (without → with) |
|---|---|---|---|---|
| Claude Code | 47% less12.1 → 6.4 s | 44% less24,271 → 13,627 | 89% less3.5 → 0.4 | 19 → 20 of 20 |
| Codex | 26% less13.8 → 10.2 s | 43% less45,395 → 26,004 | 80% less3.0 → 0.6 | 20 → 20 of 20 |
| OpenCode | 47% less18.0 → 9.6 s | 43% less13,196 → 7,528 | 87% less3.7 → 0.5 | 21 → 21 of 21 |
| Pi | 51% less16.7 → 8.2 s | 33% less9,737 → 6,495 | 85% less3.6 → 0.5 | 20 → 21 of 21 |
| Cursor | 6% less52.3 → 49.2 s | 40% less182,940 → 109,520 | 65% less8.0 → 2.8 | 26 → 24 of 27 |
Models: Claude Sonnet 5.5 (Claude Code), GPT-6.1 Sol (Codex, OpenCode, Pi), Grok 4.7 High (Cursor), at their default or low effort. Cursor's row is from its own run on the previous release; the others are from October 2026. Each tool counts tokens its own way, so compare within a row. Small benchmark; your results will vary. Method, per-task results and caveats · raw data.
Other benchmarks
| Benchmark | What it tests | Oko | Best comparison |
|---|---|---|---|
| Sense's agent benchmark | Six multi-step tasks, Claude Opus 4.7, run against Sense the same evening | Found 88% of the locations to cite, at half the cost | Sense: 63% |
| Agent Retrieval Bench | 345 tasks: find the files a developer needs next | Right file ranked first most often: 0.40, checked by the benchmark's maintainers | Best published method: 0.24 |
| SWE-Explore | 848 real issues: rank the code fixing agents needed | One search ranks it within the range of agents that explore for many turns: 0.82 | Agents: 0.72–0.95 |
Where Oko helps less
- Cursor's own search is already fast, so Oko saves less time there: mostly tokens and tool calls.
- Duplicated code can mislead it. When two files hold identical copies of a function, Oko may show the wrong one first; one Astro edit task in our benchmark fails this way.
- Big changes across many files: one search returns five places, so an issue touching many files still needs the agent's own exploring.
Use it from your terminal
oko ask "where is authentication handled?"
oko ask "how are retries handled?" --json
oko stats # what ranking has cost you
More in search options.
How it works
Oko searches your project locally (keywords, symbols and file structure), then
asks Jev, TypeSafe AI's relevance model, which of the
candidates actually answer the question, and returns those excerpts with exact
line numbers. oko setup connects it to your tool as an MCP server, adds short
guidance to the instructions your tool reads, and installs a hook that answers a
code question as you send it.
What setup changes · Privacy.
Documentation
| I want to… | Guide |
|---|---|
| Install, upgrade or troubleshoot | Installation |
| Connect a tool by hand, or understand the MCP tool | Client setup · MCP reference |
Configure keys, .env or caching |
Configuration |
| Search from the terminal, or rank my own documents | Search · Document ranking |
| See every benchmark and how it was run | Benchmark results |
| Know what leaves my machine | Privacy |
Contributing
Bug reports and ideas are welcome: open an issue
with your OS and oko --version, without keys or private code. To build and
test, see CONTRIBUTING.md.
License
MIT. Dependency attributions are in THIRD_PARTY_NOTICES.md.
Oko MCP questions
How does Oko improve coding agent performance?
Oko helps agents find relevant source code faster, resulting in fewer tool calls, lower token consumption, and reduced search time.
Is my code private when using Oko?
Yes, search runs locally on your machine, and only the specific question and selected code snippets are sent to the ranker.
Can I use Oko without an API key?
Yes, you can use a no-key mode which performs local keyword ranking only.
Which coding tools are compatible with Oko?
Oko supports Claude Code, Codex, Cursor, OpenCode, and Pi.