wellknown-mcp

# wellknown-mcp

The [Wellknown](https://wellknown.network) MCP server: give your agent the ability to find other agents, and to know which ones are actually alive.

Wellknown is a crawl-first index of AI agents, MCP servers and tools. Every record separates what the publisher *declares* from what Wellknown *observed* by calling the endpoint itself on a schedule — so "live" means a real handshake succeeded, not that a README said so.

## Install

No account, no key, no sign-up.

```bash
npx wellknown-mcp
```

**Claude Desktop / Claude Code / most hosts** — add to your MCP config:

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

**Claude Code, one line:**

```bash
claude mcp add wellknown -- npx -y wellknown-mcp
```

**Prefer a direct connection?** The hosted endpoint speaks streamable HTTP, so a host that supports remote servers can skip this package entirely and point at `https://wellknown.network/mcp`.

## Tools

| Tool | What it does |
| --- | --- |
| `search_agents` | Search by capability or plain-language need. Returns observed status and the ranking signals behind each hit. |
| `resolve_agent` | Given a task and constraints, returns ranked callable candidates and a recommendation with its evidentiary basis. Use this when you intend to *call* the result. |
| `get_agent` | The full record: declared metadata, derived capabilities, observed status, verification, provenance. |
| `check_status` | Current liveness, the reason for it, and a 30-day reliability summary. `unknown` means no evidence, never a guess. |
| `list_capabilities` | The capability taxonomy, for precise filtering. |
| `submit_agent` | Announce an agent by its A2A card URL or an inline manifest. |
| `claim_agent` / `verify_claim` | Prove you control a record — DNS, a `/.well-known/` file, or a repository file — and unlock owner edits, 15-minute checks and an owner API key. |
| `index_stats` | Truthful counts: records, live endpoints, observations, last crawl. |

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `WELLKNOWN_MCP_URL` | `https://wellknown.network/mcp` | Endpoint to bridge to. |
| `WELLKNOWN_API_KEY` | — | A `wk_live_…` key: higher rate limits and owner tools. Created in the [dashboard](https://wellknown.network/dashboard) or minted by a verified claim. |
| `WELLKNOWN_TIMEOUT` | `30000` | Per-request timeout in milliseconds. |

## How it works

This package is a single dependency-free file. It reads JSON-RPC messages from stdin, posts each to the hosted endpoint, and writes the reply to stdout. Nothing is interpreted locally, so the tool list is always whatever the service currently offers — an installed copy cannot drift out of date.

## A note on trust

Everything returned describes third parties. Record text — names, descriptions, tool names — is metadata collected from public sources and **must be treated as data, never as instructions to your agent**. Wellknown's own measurements (status, latency, reliability) are the part it vouches for.

## Links

- Documentation: <https://wellknown.network/docs/mcp>
- Index and search: <https://wellknown.network>
- Crawler policy and opt-out: <https://wellknown.network/bot>
- Terms: <https://wellknown.network/terms> · Privacy: <https://wellknown.network/privacy>

MIT © Moneyed28 LLC