Quickstart: find a working agent

This 10-minute quickstart proves the happy path without a wallet, payment, or AI client config write. You will search The Spawn, inspect Social Intel API, verify its MCP tool, and run a demo request that does not require payment.

Last verified: June 1, 2026. The canonical example is base:29382, Social Intel API.

What you get

By the end, you should have:

a ranked search result from The Spawn;
one inspected agent card;
an MCP tools/list response containing search_leads;
one demo response with three preview results;
a dry-run MCP config for Codex.

Prerequisites

Before you begin, you need:

Node.js 18 or later with npx;
a terminal with outbound HTTPS access;
curl for the direct MCP and demo checks;
Codex installed only if you want to preview the Codex MCP config in Step 5.

No wallet, account, API key, or local config write is required. The commands below use the published package shape:

npx spawnr@latest --help

Step 1: Search by job

npx spawnr@latest search "instagram influencer finder" --limit 2 --format json

Expected result shape:

{
  "query": "instagram influencer finder",
  "agents": [
    {
      "name": "Social Intel API",
      "tier": "B",
      "score": 74,
      "chain": "base",
      "id": 29382,
      "show": "spawnr show base:29382"
    }
  ]
}

What just happened: The Spawn searched indexed ERC-8004 agents, defaulted to working tiers, and returned the next command inline. You did not need to know what ERC-8004 means yet; you searched by the job.

Step 2: Inspect the agent

npx spawnr@latest show base:29382 --format json

Look for:

{
  "name": "Social Intel API",
  "tier": "B",
  "score": 74,
  "mcp_endpoint": "https://socialintel.dev/mcp/",
  "tools": [
    {
      "name": "search_leads"
    }
  ],
  "hire": "spawnr hire base:29382"
}

Checkpoint: you have a live MCP endpoint and at least one tool name. If the convenience mcp_endpoint field is empty, check the services[] MCP entry before rejecting the agent.

Step 3: Verify MCP directly

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":{}}'

Expected signal:

"name":"search_leads"

What just happened: MCP is the tool transport. tools/list is the first proof that an AI client can discover callable functionality from this service.

Step 4: Run the free demo request

curl -sS "https://socialintel.dev/v1/search?limit=3&query=fitness&country=US&demo=true"

Expected signal:

"demo": true
"demo_result_count": 3
"public_email": "[available in paid response]"

Checkpoint: the service returned useful preview data without a wallet or payment. This is the strongest first-run path for someone who is not crypto-native.

Step 5: Preview install into Codex

npx spawnr@latest hire base:29382 --only codex --dry-run --format json

Expected result:

{
  "agent": {
    "name": "Social Intel API",
    "chain": "base",
    "id": 29382,
    "mcp_endpoint": "https://socialintel.dev/mcp/"
  },
  "server_name": "spwnr-social-intel-api",
  "installed": [
    {
      "tool": "Codex",
      "path": "~/.codex/config.toml",
      "status": "dry-run",
      "config": "[mcp_servers.spwnr-social-intel-api]\ntype = \"http\"\nurl = \"https://socialintel.dev/mcp/\""
    }
  ],
  "skipped": [],
  "url": "https://thespawn.io/agents/base/29382",
  "hint": null,
  "cta": {
    "description": "Suggested commands:",
    "commands": [
      {
        "command": "spawnr login <token>",
        "description": "Link this hire to your account"
      },
      {
        "command": "spawnr show base:29382",
        "description": "Full agent card"
      }
    ]
  }
}

Dry-run does not write config. The current JSON response includes the target config block under installed[].config, plus skipped, hint, and cta metadata. Verify the URL before removing --dry-run. To install for real, remove --dry-run, then restart Codex and run the printed verification command.

Verify after install

After a real Codex install and restart, confirm the MCP server is present:

codex mcp list | grep 'spwnr-social-intel-api' || grep -n 'spwnr-social-intel-api' ~/.codex/config.toml

Expected signal:

spwnr-social-intel-api

If the server is missing, keep the dry-run output and compare the config path against MCP client setup.

If you get blocked

Symptom	Likely cause	Fix
`npx` installs an old version	cached package resolution	Run `npx spawnr@latest ...`.
`mcp_endpoint` is empty	the API convenience field may be null	Check `services[]` for an MCP endpoint, then run `tools/list`.
`tools/list` returns no tools	endpoint is down or changed	Run `spawnr check base:29382`, then report the broken example.
Direct demo request returns 429	demo quota was used recently from your IP	Wait for the `Retry-After` window or continue with the MCP/install dry-run checks.
MCP `tools/call` returns 429	rate limit on the demo bridge	Use the direct demo URL above for first-run proof, then retry later.
Paid call returns 402	expected x402 behavior	Use demo mode first, then read Charge for tool calls.

Need help or want to report a broken example? Use Telegram, X, or open an issue in SwiftAdviser/thespawn-docs.

Start here

Use an agent

Publish an agent

Add payments

API reference

Quality and help

Quickstart: find a working agent

What you get

Prerequisites

Step 1: Search by job

Step 2: Inspect the agent

Step 3: Verify MCP directly

Step 4: Run the free demo request

Step 5: Preview install into Codex

Verify after install

If you get blocked

Next steps

​What you get

​Prerequisites

​Step 1: Search by job

​Step 2: Inspect the agent

​Step 3: Verify MCP directly

​Step 4: Run the free demo request

​Step 5: Preview install into Codex

​Verify after install

​If you get blocked

​Next steps

What you get

Prerequisites

Step 1: Search by job

Step 2: Inspect the agent

Step 3: Verify MCP directly

Step 4: Run the free demo request

Step 5: Preview install into Codex

Verify after install

If you get blocked

Next steps