Add WellKnown to your agent

One endpoint, every client. Your agent gets five tools: search the open registry, resolve one capability, audit any domain's discoverability, validate a catalog, and generate one.

https://wellknownhq.com/mcp

The snippets below carry a ?via= tag naming the client, so we can tell which of these instructions people actually get working. It counts connections and tool calls per client and nothing else, the totals are public at /metrics.json, and deleting it changes nothing except our ability to fix the instructions that do not work.

Every client names the same thing differently

There is no agreed shape for "here is a remote MCP server". Four different top-level keys and two different names for the URL, across clients that all speak the same protocol. Find yours below.

This is the fragmentation problem in miniature, which is roughly the reason this product exists.

In the app — no terminal, no config file

Claude Desktop

1. Settings → Connectors → Add custom connector
2. Name: WellKnown · URL: https://wellknownhq.com/mcp
3. Leave OAuth Client ID and Client Secret empty — this server registers clients automatically
4. Add, then Connect: your browser opens, you sign in, you approve

Signing in is what scopes the connection to you: your private capabilities, and anything a service has connected to your Wellknown ID, ride it with no key anywhere. The same flow works in Claude’s web and mobile apps under Settings → Connectors.

Command line, one line

Claude Code

claude mcp add --transport http wellknown "https://wellknownhq.com/mcp?via=claude-code"

Goose

goose configure

Choose Add Extension → Remote Extension (Streamable HTTP), name it wellknown, and paste https://wellknownhq.com/mcp?via=goose as the URI.

Config file

Claude Desktop

claude_desktop_config.json — for managed or scripted installs; the Connectors screen above is the ordinary path.

{
  "mcpServers": {
    "wellknown": { "type": "http", "url": "https://wellknownhq.com/mcp?via=claude-desktop" }
  }
}

Cursor

.cursor/mcp.json, or ~/.cursor/mcp.json for every project

{
  "mcpServers": {
    "wellknown": { "url": "https://wellknownhq.com/mcp?via=cursor" }
  }
}

VS Code

.vscode/mcp.json. Note the key is servers, not mcpServers.

{
  "servers": {
    "wellknown": { "type": "http", "url": "https://wellknownhq.com/mcp?via=vscode" }
  }
}

OpenClaw

~/.openclaw/openclaw.json, then restart the gateway

mcp: {
  servers: {
    wellknown: {
      url: "https://wellknownhq.com/mcp?via=openclaw",
      transport: "streamable-http"
    }
  }
}

OpenClaw requires transport on remote servers and its schema is strict, so an unknown key or a missing transport is rejected outright rather than ignored. It also refuses non-HTTPS URLs except on loopback.

Hermes

~/.hermes/config.yaml, then /reload-mcp in a session

mcp_servers:
  wellknown:
    url: "https://wellknownhq.com/mcp?via=hermes"
    enabled: true

Omit transport for Streamable HTTP; set it to sse only for SSE servers. Hermes discovers and registers the tools at startup.

Windsurf

~/.codeium/windsurf/mcp_config.json. Note serverUrl, not url.

{
  "mcpServers": {
    "wellknown": {
      "type": "streamable-http",
      "serverUrl": "https://wellknownhq.com/mcp?via=windsurf"
    }
  }
}

Cline

MCP Servers icon → Configure MCP Servers → cline_mcp_settings.json

{
  "mcpServers": {
    "wellknown": {
      "type": "streamableHttp",
      "url": "https://wellknownhq.com/mcp?via=cline"
    }
  }
}

Zed

settings.json. Zed calls them context servers, and native HTTP needs v0.214.5 or later.

{
  "context_servers": {
    "wellknown": { "url": "https://wellknownhq.com/mcp?via=zed" }
  }
}

Point and click

ChatGPT

1. Settings → Connectors → Advanced settings, turn on Developer mode.
2. Back in Connectors, add a custom connector and paste https://wellknownhq.com/mcp?via=chatgpt.
3. Leave authentication as none. Save.

Custom connectors need a Pro or Max plan. On Business and Enterprise an admin must first allow them under Workspace Settings → Permissions & Roles → Connected Data.

Claude, in the app

1. Settings → Connectors → Add custom connector.
2. Paste https://wellknownhq.com/mcp?via=claude-app, leave authentication empty, and add it.

No client at all

Plain JSON-RPC, which is useful for testing that a config actually works:

curl -s "https://wellknownhq.com/mcp?via=curl" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Or skip MCP entirely and query the registry directly. It is a plain HTTP endpoint, so any agent framework can call it with no integration at all:

curl -s https://wellknownhq.com/registry/search \
  -H 'Content-Type: application/json' \
  -d '{"query":{"text":"track a shipment"},"pageSize":5}'

Check it worked

Ask your agent any of these. If it answers with real data, the tools are wired up.

• "Can AI agents find stripe.com? Use the wellknown tools."
• "Search the WellKnown registry for something that can track a shipment."
• "Validate this ai-catalog.json for me."

Five tools should appear: search_registry, get_capability, audit_domain, validate_catalog, generate_catalog. If your client lists zero tools, it usually means the transport field is wrong or missing rather than the URL.

Your own capabilities, on the same endpoint

Everything above is anonymous and stays anonymous. This part is for organisations that also keep a private registry here: add one header, and your own internal capabilities come back in the same results as the public index, ranked together, each labelled with which it is.

Authorization: Bearer wk_...

Same URL, same five tools, same schemas. search_registry answers over your private entries and the public commons in one call, filtered to the scopes on that key. The audit tools are unaffected either way: an audit measures a public domain and has nothing to do with your key.

No registry of your own? Starting one is free and needs no network on either side: your first capability is useful to your own agents on day one. Nothing on this page requires it.

What stays free

All of it. The anonymous endpoint is not a trial of this one. With no Authorization header the server answers exactly as it did before keys existed: same tools, same results, same status, no account anywhere in the path. A key does not unlock the public index. It adds your own entries to the answer, and only for you.

When you do not need a key at all

Claude Desktop, and Claude’s web and mobile apps, sign in with OAuth from the Connectors screen — the browser flow above. That session carries the same identity a key would, so private capabilities and connected services work with no key minted and nothing pasted anywhere. Keys exist for the clients that cannot open a browser: command lines, config files, unattended agents.

What a key asserts

That it belongs to an account we issued it to. That is the whole claim. It is a bearer token, so whoever holds the string can present it, and we cannot tell an agent you wrote from a script that read your config file. It is not a verified statement about which software is calling, and we will not describe it as one. Give each agent its own key, scope it to the least it needs, and revoke it when that agent is retired.

A key we do not recognise is an error, not a downgrade

A revoked or mistyped key gets 401. It never falls back quietly to public-only results. Absent means anonymous; present and wrong means we say so, because an integration that silently returns less than it should is the worst possible way to find out a key expired.

Browser clients

A response to a request carrying a key is never CORS-readable, deliberately: your private capability list must not be readable by whatever page a browser happens to have open. That holds on both surfaces. The anonymous /registry/search answer stays open to any origin, because everything in it is already public.

Claude Code

claude mcp add --transport http wellknown "https://wellknownhq.com/mcp?via=claude-code" \
  --header "Authorization: Bearer wk_..."

Claude Desktop

{
  "mcpServers": {
    "wellknown": {
      "type": "http",
      "url": "https://wellknownhq.com/mcp?via=claude-desktop",
      "headers": { "Authorization": "Bearer wk_..." }
    }
  }
}

Cursor

{
  "mcpServers": {
    "wellknown": {
      "url": "https://wellknownhq.com/mcp?via=cursor",
      "headers": { "Authorization": "Bearer wk_..." }
    }
  }
}

VS Code

inputs prompts for the key and keeps it out of the file, which matters because .vscode/mcp.json is usually committed.

{
  "inputs": [
    { "type": "promptString", "id": "wk-key", "description": "WellKnown API key", "password": true }
  ],
  "servers": {
    "wellknown": {
      "type": "http",
      "url": "https://wellknownhq.com/mcp?via=vscode",
      "headers": { "Authorization": "Bearer ${input:wk-key}" }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "wellknown": {
      "type": "streamable-http",
      "serverUrl": "https://wellknownhq.com/mcp?via=windsurf",
      "headers": { "Authorization": "Bearer wk_..." }
    }
  }
}

Cline

{
  "mcpServers": {
    "wellknown": {
      "type": "streamableHttp",
      "url": "https://wellknownhq.com/mcp?via=cline",
      "headers": { "Authorization": "Bearer wk_..." }
    }
  }
}

No client at all

curl -s "https://wellknownhq.com/mcp?via=curl" \
  -H 'Authorization: Bearer wk_...' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry","arguments":{"query":"what can you do"}}}'

Or skip MCP and send the same header to https://wellknownhq.com/registry/search, which merges the two indexes the same way.

The clients missing from this list are the ones whose header handling we have not checked against their own schema, and a guessed snippet is worse than a gap. Every one of them works anonymously today. Tell us which one and we will check it and add it.

Discoverable without any of this, too: /.well-known/mcp.json, /mcp/server-card, and /.well-known/ai-catalog.json. A client that supports discovery can find the server from the domain alone.