Wayfindr: an open-source tool discovery layer for MCP
Let your agents discover tools without paying the enumeration tax on every run.
If you read my post on natural language tool search then you’re aware I made a tool discovery layer for MCP. I call it Wayfindr, and it’s open source under the Apache 2.0 license. To be honest, this project has been a long time coming. I built it for three main reasons:
- Reauthenticating to my local MCP servers is such a pain. I have no idea why harnessess haven’t figured this out yet
- Claude Code, Codex, Opencode, and other harnessess are good at finding tools they want to use, but configurations are not portable between them. Want to try out a new harness? Have fun setting up your connectors again 🤡
- I’m tired of stupid “plugins” to bridge the gap for MCP servers that don’t support DCR. No, Claude/Codex/etc, I don’t want to install your slack plugin 🙄. I just want to connect to the official MCP server and move on with my life.
Wayfindr concretely addresses all of these gaps:
- It keeps your tokens current. One daemon owns every refresh, and refreshes are single-flight per credential. Two harnesses can’t race a rotating refresh token and log you out. It refreshes right before a call (or on a 401), not on a timer.
- Wayfindr is external to all harnesses. It’s literally a proxy layer that sits between any MCP server and a harness. Tools and elicitation go through; more on that below.
- No DCR? No problem. Headless box? Device code. M2M? JWT bearer? Private keys? mTLS? DPoP? Yes, yes, yes, yes, and yes. Wayfindr also speaks the real-world dialects, like Slack’s “HTTP 200, but actually an error” and Google’s offline access. API key or bearer token? Static headers. It doesn’t choke on OAuth and it doesn’t assume how any MCP sevrer does auth.
How it works
Your harness doesn’t see your connectors’ tools. It sees two:
search_tools: say what you want in words, get back the few tools that fitcall_tool: run one by its qualified name, likelinear.create_issue
Setup is a handful of commands:
wayfindr init # config, master key, store, and client tokenwayfindr start # run the daemon in the backgroundwayfindr connector add linear --url https://mcp.linear.app/mcpwayfindr auth linearclaude mcp add --scope user --transport stdio wayfindr -- wayfindr stdiowayfindr init prints the line for every supported harness, so trying a new one is a copy and
paste. Connect once and the next harness you try inherits everything.
Search is hybrid: BM25F with trigram typo tolerance, optionally blended with vectors via reciprocal
rank fusion. A query that exactly matches a tool’s name ranks that tool first, and
wayfindr search "open a ticket" --explain shows why each result landed where it did.
Embeddings only ever add results. If your embedding server is slow or down, the query times out after 2s and falls back to lexical search instead of failing. Swap models and Wayfindr re-embeds in the background while search keeps working.
Results stay lean on purpose. detail: "brief" returns schema-less entries (15 per page, up to 25),
and names: [...] fetches full definitions for up to 10 tools once the agent has picked. You only
pay for the schemas you actually use. That’s the enumeration tax, paid in installments.
When a connector needs sign-in, search_tools and failed calls hand the agent a local auth link
(http://127.0.0.1:7777/auth/linear). Your agent can tell you to sign in mid-task instead of dying
with an opaque error. Credential health warnings show up before a token expires, too.
What it can sign in with
You pick a grant per connector:
| Grant | Who signs in | Good for |
|---|---|---|
| Authorization code (default) | You, in a browser | Linear, Slack, Gmail, GitHub |
Device code (--device) | You, on any device | A server you reach over SSH |
client_credentials | Nobody | Bots and CI jobs |
jwt_bearer | Nobody, a workload token stands in | Kubernetes, GitHub Actions OIDC |
The unattended grants hold the token in memory only and just fetch a new one when a call needs it. Nothing hits disk.
On top of the grant, you choose how Wayfindr proves which OAuth client it is: a client secret, a
client_secret_jwt, a private_key_jwt, or a client certificate over mTLS. You can also bind
tokens to a key only Wayfindr holds with DPoP, which defaults to auto and turns on when the server
asks. Private keys look like this:
[connectors.corp.auth]type = "oauth"client_id = "wayfindr"token_endpoint_auth_method = "private_key_jwt"
[connectors.corp.auth.signing_key]key = "${secret:corp_signing_key}"Okta, Entra ID, Keycloak, and Ping are covered in the docs, since that’s where this stuff usually bites.
A few honorable mentions:
- Credentials are encrypted in your DB (SQLite or Postgres) with AES-256-GCM. The master key lives
in
WAYFINDR_SECRET_KEY, your OS keychain, or a0600master.key, checked in that order. The tool catalog and call log are not encrypted - Wayfindr is a cli-first tool, but has a minimal web ui. It can add connectors, sign you in (device codes included), and create and revoke client tokens, but it can’t edit or remove connectors
- Per-connector tool policy that goes past an allow list:
@read,@write, globs, and!deny.tools = ["@write", "!merge_pull_request"]means nothing destructive and no merging. The daemon enforces it on every call, which matters because your harness only ever seescall_tool - Scoped tokens for unattended agents.
wayfindr token create nightly --connector githublimits a token to the connectors you name and blocks the admin API. Only its SHA-256 is stored - Import from the harness you already use:
wayfindr connector import claude-code --dry-run(alsoclaude-desktop,cursor,codex, andvscode) moves literal credentials into encrypted secrets - A call log.
wayfindr callsrecords the client, tool, duration, and outcome. Never arguments or results. Calls are kept for 30 days - Project scopes and named profiles for repeatable access across projects. Both only narrow. A
.wayfindr.tomlcan hide connectors and tools but can’t define them, since a cloned repo is untrusted. A profile isn’t a security boundary either; the client picks it - Supports the current stateless spec as well as legacy MCP versions and transports (SSE). Client and upstream versions negotiate separately, so an older server still works with a newer harness
- Supports URL elicitation, and bridges a 2025-era server’s
elicitation/createfor newer clients. Plain HTTP clients on older spec versions (Codex, for example) need thewayfindr stdioshim - BYO embedding model for any OpenAI-style embedding API (e.g. ollama, lemonade, etc.). The docs recommend Qwen3-Embedding-0.6B at 1024 dimensions
Things not supported today:
- MCP extensions
- Resources, prompts, sampling, and roots. Wayfindr proxies tools and elicitation
- Integration with external credential stores (e.g. 1password, infisical, bitwarden, etc.). You can
pipe a secret in with
op read ... | wayfindr secret set name, though - Token exchange (RFC 8693), SAML bearer, UMA, and the implicit and password grants. The last two are dead in OAuth 2.1 anyway
- Revoking a token at the provider.
wayfindr auth revokeforgets it locally, so kill the grant in the provider’s settings too - Tools in your harness’s native tool list. Your harness sees
search_toolsandcall_tool, notlinear.create_issuedirectly
The plumbing isn’t the hard part. Connect a server once and every harness you try next inherits it. The code’s at atomicpages/wayfindr. Kick the tires and tell me what breaks.