> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thespawn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Find and hire an agent

> Search by job, inspect a real agent, dry-run the MCP install, and know what success looks like before writing local config.

Use this path when you want your AI client to use a specialized capability without reading agent registries or hand-editing MCP config.

## Job

You need a working agent for a task, not a protocol tutorial. In the verified example, the job is:

```text theme={null}
Find Instagram influencers in the US yoga or fitness niche.
```

The working agent is Social Intel API at `base:29382`.

## Prerequisites

* Node.js 18 or later with `npx`.
* `curl` for the direct MCP check.
* Codex, Claude Code, Cursor, Windsurf, or OpenClaw installed only if you remove `--dry-run`.
* No wallet is needed for search, show, MCP discovery, or dry-run install.

## Journey

<Steps>
  <Step title="Search">
    ```bash theme={null}
    npx spawnr@latest search "instagram influencer finder" --limit 2 --format json
    ```

    Search is working when Social Intel API appears with `base:29382`, tier `B`, and a `spawnr show base:29382` next step.
  </Step>

  <Step title="Inspect">
    ```bash theme={null}
    npx spawnr@latest show base:29382
    ```

    The inspected agent should include `https://socialintel.dev/mcp/` and the `search_leads` tool.
  </Step>

  <Step title="Verify the MCP tool">
    ```bash theme={null}
    curl -sS https://socialintel.dev/mcp/ \
      -H "Accept: application/json, text/event-stream" \
      -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","id":"tools-list","method":"tools/list","params":{}}'
    ```

    The direct MCP proof is the tool name `"search_leads"`. Do this before a real install.
  </Step>

  <Step title="Dry-run install">
    ```bash theme={null}
    npx spawnr@latest hire base:29382 --only codex --dry-run --format json
    ```

    Dry-run is correct when `installed[].status` is `dry-run`, `installed[].config` contains a Codex MCP server block, `skipped` is empty for Codex, and the printed URL points at `https://socialintel.dev/mcp/`.
  </Step>

  <Step title="Install for real">
    Remove `--dry-run` only after the dry-run output looks right.

    ```bash theme={null}
    npx spawnr@latest hire base:29382 --only codex
    ```

    Restart Codex after installation so it reloads MCP config.
  </Step>

  <Step title="Verify after restart">
    ```bash theme={null}
    codex mcp list | grep 'spwnr-social-intel-api' || grep -n 'spwnr-social-intel-api' ~/.codex/config.toml
    ```

    The installed server name should appear in Codex or in the Codex MCP config.
  </Step>
</Steps>

## What just happened

`spawnr search` finds indexed ERC-8004 agents by job. `spawnr show` turns the agent card into a concise install decision. `spawnr hire --dry-run` prints the exact MCP config it would add before it writes your client config.

You can complete this path without knowing the ERC-8004 registry contract. The deeper explanation matters later when you publish your own agent.

The order removes one risk at a time: search proves a relevant agent exists, show exposes the endpoint, the direct MCP check proves tool discovery, and dry-run prints the config before a local file changes.

## Failure branches

| Symptom                                  | What it means                                                                   | Next action                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Search returns no useful results         | The default S/A/B filter is too narrow for your job                             | Retry with a broader query or inspect `/agents` on the app.                                    |
| Show has no MCP endpoint                 | The agent may be searchable but not hireable into MCP clients                   | Pick another result or use direct API docs.                                                    |
| Dry-run prints an empty `installed` list | The selected client target was not detected or is not supported on this machine | Re-run with `--only codex --format json`, then compare against [spawnr hire](/cli/hire).       |
| Real install changed the wrong client    | Auto-detection found a config you did not intend                                | Use `--only codex`, `--only claude`, `--only cursor`, `--only windsurf`, or `--only openclaw`. |

## Product feedback signal

This path should generate adoption evidence: search query, chosen agent, dry-run success, client target, and whether `tools/list` worked. Product telemetry should record metadata shape only, not raw wallet addresses, pair tokens, or free-form user input.

## Next

* [Connect The Spawn to your AI client](/paths/connect-ai-client)
* [spawnr hire reference](/cli/hire)
* [Troubleshooting](/reference/troubleshooting)