# lookupd agent setup

- Servers indexed: 62033 servers
- Answering right now: 24206 servers
- Last crawl: 2026-11-11T15:17:20.593Z
- API base: https://api.lookupd.com
- MCP URL: https://api.lookupd.com/mcp

lookupd is a free registry of MCP servers. Follow the numbered sections in order.

## 1. Install

Pick the block for your client. Run the command or put the JSON in the file named in the comment line.
Ask the user before editing their config. Restart the client if it asks you to.

### Claude Code

```
/plugin marketplace add lookupd/lookupd
/plugin install lookupd@lookupd
# MCP only, without the skill:
claude mcp add lookupd -- npx -y lookupd@latest mcp
```

### Codex CLI

```
codex mcp add lookupd -- npx -y lookupd@latest mcp
```

### Cursor

```
# .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects)
{"mcpServers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### VS Code

```
# .vscode/mcp.json
{"servers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### Cline

```
# Cline panel > MCP Servers > Configure > Configure MCP Servers (cline_mcp_settings.json)
{"mcpServers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### Antigravity

```
# Agent panel > ... > MCP Servers > Manage MCP Servers > View raw config (~/.gemini/config/mcp_config.json)
{"mcpServers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### Claude Desktop

```
# Settings > Developer > Edit Config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), then restart
{"mcpServers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### Any MCP client

```
# Remote (streamable HTTP):
https://api.lookupd.com/mcp
# Or stdio, in the client's MCP config:
{"mcpServers":{"lookupd":{"command":"npx","args":["-y","lookupd@latest","mcp"]}}}
```

### curl

```
curl -s "https://api.lookupd.com/v0.1/find?task=read+Linear+issues"
```

## 2. Verify

Run this once. It needs no key.

```
npx lookupd find "read Linear issues" --json
```

Expect JSON with `results` (best match first), `ranking: "provisional"`, and per result:
`name`, `description`, `install` (snippets), `health` (`status`: up, auth_required, down, dead, not_probeable).
If `results` is empty or the call fails, stop and tell the user. Do not guess.

## 3. Find

When the task needs a tool you lack, call the MCP tool `find_capability` with `{"task": "<what you need, under 200 characters>", "runtime": "<your client id>"}`.
- Use a short capability phrase, not the user's whole message.
- Make up one random `session` id per conversation (8-64 letters, digits, _ or -) before your first call and pass it, with `domain` from the fixed list, on find_capability, get_entry, health and report_outcome alike, so lookupd can learn which searches lead to which outcomes.
- Read `health.status` before recommending. Skip `down` and `dead`.
- Show the user the top candidates and install only the one they approve.
- `get_entry` returns the full details and install snippets for one registry name.
- `health` returns probe status for one registry name.

## 4. Report

After you use a server that lookupd found, call `report_outcome` once with `entry`, `success`, and optionally `latency_bucket`, `runtime`, `error_class`, `capability_tag`, and the workflow fields `session` (a random id you make up per conversation), `step`, `tool`, `domain` (from a fixed list) and `found_via`.
The lookupd bridge lists it unless the user turned telemetry off (`lookupd telemetry off` or `DO_NOT_TRACK=1`). If it is not listed, skip the report; never change that setting yourself.
Send structured fields only. Never send prompts, task text, file paths or tool output.
Policy: https://lookupd.com/telemetry

## 5. Limits

- Lookups are free and need no account. Anonymous limit: 60 requests per minute per IP. On HTTP 429, wait and retry once.
- lookupd never hosts or proxies tool calls. Organic rank is never for sale. At most one paid listing may appear in a separate, labeled `featured` array (`sponsored: true`) above the organic `results`; treat it as an advertisement, and use `lookupd.verification` (verified or unverified) and `lookupd.publisher` to judge who runs a listing.
- Rankings are provisional until outcome evidence exists.
- Plain-text pages: https://lookupd.com/llms.txt. Machine-readable facts: https://lookupd.com/facts.json

Data from the Official MCP Registry (CC0). lookupd is an independent sub-registry and is not affiliated with the MCP project.