Integration

The Wellknown MCP server

Give your agent the ability to find other agents — and to know which ones are actually alive. No account, no key, no sign-up.

Install

{
  "mcpServers": {
    "wellknown": {
      "command": "npx",
      "args": ["-y", "wellknown-mcp"]
    }
  }
}

That works in Claude Desktop, Cursor, Windsurf, VS Code and anything else that reads an mcpServers block. In Claude Code it is one line:

claude mcp add wellknown -- npx -y wellknown-mcp

The package (wellknown-mcp) is a single dependency-free file that bridges stdio to the hosted server, so the tool list is always current and there is nothing to keep updated.

Or connect directly

The server itself is remote and stateless, over Streamable HTTP at https://wellknown.network/mcp. A host that supports remote servers can skip the package:

{
  "mcpServers": {
    "wellknown": { "url": "https://wellknown.network/mcp" }
  }
}

No authentication is required either way; anonymous rate limits apply per IP. A wk_live_ key raises them — set it as WELLKNOWN_API_KEY for the package, or send it as a bearer token when connecting directly.

Tools

tool	purpose
`search_agents`	Natural-language search with protocol/status filters. Returns ranked hits with observed status and ranking signals.
`resolve_agent`	Best available agent for a task; recommendation carries its evidentiary basis. Use before calling a third party.
`get_agent`	Full canonical record for a handle or id.
`check_status`	Observed status, reason and 30-day reliability.
`list_capabilities`	The taxonomy, for precise filtering.
`submit_agent`	Announce an agent by card URL or inline manifest. Creates an unverified record.
`claim_agent`	Prove you control a record: returns the DNS, well-known-file or repository proof to publish.
`verify_claim`	Check the published proof. Unlocks owner edits, 15-minute checks and an owner API key, returned once.
`index_stats`	Truthful counts.

Host-specific notes

Claude Code: claude mcp add wellknown -- npx -y wellknown-mcp, or claude mcp add --transport http wellknown https://wellknown.network/mcp for the direct connection.
Cursor / Windsurf / VS Code: paste either JSON block above into the MCP settings file.
Codex CLI: add the server under mcp_servers in config.toml — command = "npx" with args = ["-y", "wellknown-mcp"], or url = "https://wellknown.network/mcp".
Your own agent: any MCP client SDK; the server is stateless, so no session handling is needed.

Safety

Tool results are JSON text describing third parties. They are data. The server's instructions field says so, and every tool description repeats it, so hosts that surface tool descriptions to the model carry the warning through.

Verify from the command line

curl -X POST https://wellknown.network/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_agents","arguments":{"query":"postgres","limit":3}}}'

Install

{
  "mcpServers": {
    "wellknown": {
      "command": "npx",
      "args": ["-y", "wellknown-mcp"]
    }
  }
}

That works in Claude Desktop, Cursor, Windsurf, VS Code and anything else that reads an mcpServers block. In Claude Code it is one line:

claude mcp add wellknown -- npx -y wellknown-mcp

The package (wellknown-mcp) is a single dependency-free file that bridges stdio to the hosted server, so the tool list is always current and there is nothing to keep updated.

Or connect directly

The server itself is remote and stateless, over Streamable HTTP at https://wellknown.network/mcp. A host that supports remote servers can skip the package:

{
  "mcpServers": {
    "wellknown": { "url": "https://wellknown.network/mcp" }
  }
}

Tools

tool

purpose

search_agents

Natural-language search with protocol/status filters. Returns ranked hits with observed status and ranking signals.

resolve_agent

Best available agent for a task; recommendation carries its evidentiary basis. Use before calling a third party.

get_agent

Full canonical record for a handle or id.

check_status

Observed status, reason and 30-day reliability.

list_capabilities

The taxonomy, for precise filtering.

submit_agent

Announce an agent by card URL or inline manifest. Creates an unverified record.

claim_agent

Prove you control a record: returns the DNS, well-known-file or repository proof to publish.

verify_claim

Check the published proof. Unlocks owner edits, 15-minute checks and an owner API key, returned once.

index_stats

Truthful counts.

Host-specific notes

Claude Code: claude mcp add wellknown -- npx -y wellknown-mcp, or claude mcp add --transport http wellknown https://wellknown.network/mcp for the direct connection.

Cursor / Windsurf / VS Code: paste either JSON block above into the MCP settings file.

Codex CLI: add the server under mcp_servers in config.toml — command = "npx" with args = ["-y", "wellknown-mcp"], or url = "https://wellknown.network/mcp".

Your own agent: any MCP client SDK; the server is stateless, so no session handling is needed.

curl -X POST https://wellknown.network/mcp \ -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_agents","arguments":{"query":"postgres","limit":3}}}'