Skip to content
Threadbare
MCP··7 min read

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:

  1. Reauthenticating to my local MCP servers is such a pain. I have no idea why harnessess haven’t figured this out yet
  2. 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 🤡
  3. 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:

  1. 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.
  2. 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.
  3. 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 fit
  • call_tool: run one by its qualified name, like linear.create_issue

Setup is a handful of commands:

Terminal window
wayfindr init # config, master key, store, and client token
wayfindr start # run the daemon in the background
wayfindr connector add linear --url https://mcp.linear.app/mcp
wayfindr auth linear
claude mcp add --scope user --transport stdio wayfindr -- wayfindr stdio

wayfindr 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:

GrantWho signs inGood for
Authorization code (default)You, in a browserLinear, Slack, Gmail, GitHub
Device code (--device)You, on any deviceA server you reach over SSH
client_credentialsNobodyBots and CI jobs
jwt_bearerNobody, a workload token stands inKubernetes, 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:

  1. 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 a 0600 master.key, checked in that order. The tool catalog and call log are not encrypted
  2. 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
  3. 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 sees call_tool
  4. Scoped tokens for unattended agents. wayfindr token create nightly --connector github limits a token to the connectors you name and blocks the admin API. Only its SHA-256 is stored
  5. Import from the harness you already use: wayfindr connector import claude-code --dry-run (also claude-desktop, cursor, codex, and vscode) moves literal credentials into encrypted secrets
  6. A call log. wayfindr calls records the client, tool, duration, and outcome. Never arguments or results. Calls are kept for 30 days
  7. Project scopes and named profiles for repeatable access across projects. Both only narrow. A .wayfindr.toml can 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
  8. 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
  9. Supports URL elicitation, and bridges a 2025-era server’s elicitation/create for newer clients. Plain HTTP clients on older spec versions (Codex, for example) need the wayfindr stdio shim
  10. 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:

  1. MCP extensions
  2. Resources, prompts, sampling, and roots. Wayfindr proxies tools and elicitation
  3. 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
  4. Token exchange (RFC 8693), SAML bearer, UMA, and the implicit and password grants. The last two are dead in OAuth 2.1 anyway
  5. Revoking a token at the provider. wayfindr auth revoke forgets it locally, so kill the grant in the provider’s settings too
  6. Tools in your harness’s native tool list. Your harness sees search_tools and call_tool, not linear.create_issue directly

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.