stellar-agent-search

A read-only discovery layer on top of the stellar-8004 registry — the ERC-8004-style Identity/Reputation/Validation contracts on Stellar mainnet. It adds no contracts and forks nothing: it exposes the existing on-chain registry to MCP clients, keeps indexed reputation explicitly declared-vs-verified, and proves the full agent-finds-agent loop with recorded mainnet transactions.

npm · GitHub · Docs · Evidence package

There are two official interfaces, not two copies of the stack. TypeScript applications, registration, and signed writes use the canonical @trionlabs/stellar8004 SDK from trionlabs/stellar-8004; MCP clients and terminal discovery use this package, which exact-pins that SDK internally. The upstream repo's restricted Supabase Studio /mcp is database-operator tooling behind SSH/IP controls, not an agent-registry MCP and must never be exposed as this runtime. See the integration boundary.

A read-only, keyless MCP server (and human CLI) that lets an AI agent — or you — discover, rank, and vet on-chain stellar-8004 agents on Stellar mainnet, then prepare an x402 (USDC pay-per-call) payment. One binary speaks the Model Context Protocol over stdio to Claude Code / Cursor / Windsurf / Cline / VS Code, and doubles as a plain-terminal tool. A separate Cloudflare Worker implementation exposes the same surface over stateless Streamable HTTP, but that remote endpoint is not live yet; use the local stdio transport until its deployment canary passes.

npx -y stellar-agent-search@0.1.0 find "a paid web scraper with a good reputation"

Why this exists: declared data vs. what the chain read can prove

Off-chain agent directories (A2A cards, the MCP Registry, OASF, NANDA) list self-declared agents. That is exactly where the trust gap lives. A 2026 study of the ERC-8004 ecosystem (arXiv 2606.26028) found that only 3–15% of registrations have a live endpoint, and 59–91% of "reviewers" are Sybils.

stellar-8004 is the only non-EVM ERC-8004 implementation we are aware of running on mainnet (66 agents on Stellar mainnet as of July 2026; get_registry_stats returns the current count). No published survey enumerates non-EVM deployments — the study above restricts itself to Ethereum, BSC and Base, "the three chains with the highest registration and feedback volume" — so read that as unrefuted, not as proven. This server adds something a directory listing cannot give you: a bounded Reputation-contract reachability probe. The current path calls get_clients_paginated once with a six-slot observation window. The contract exposes no authoritative client count/cursor, and expired client-index entries create holes, so even an empty or short page cannot prove that no later live client exists. Calling get_summary over that set would manufacture a false match or mismatch; this release therefore does not call it and verifies no reputation fields. An attempted, reachable probe returns unavailable with reason client-set-exhaustion-unprovable; verifiedFields is empty and average, feedback count, and unique clients all remain unverified. verified/partial/mismatch are reserved for a future authoritative aggregate. The full status set remains verified | partial | mismatch | unavailable | skipped. Self-declared marketing text (name, description, service labels, feedback tags) remains untrusted data, never instructions (see Security).

That fail-closed boundary — plus a versioned declared-evidence heuristic — is the product. Normalized Explorer quality is multiplied by fixed evidence strength (0.4 × capped volume + 0.6 × effective breadth). Effective unique clients cannot exceed feedback rows, and repeated rows per declared client are capped. These are cost-of-manipulation proxies, not chain verification, proof of personhood, or Sybil resistance.

What it exposes

All three MCP primitives, all read-only:

Tools

Full per-tool reference (inputs, outputs, defaults): docs/tools.md.

Resources — stellar8004:// (pinnable context)

registry · leaderboard · health · agent/{id} · agent/{id}/card · agent/{id}/feedback · agent/{id}/reputation · owner/{address}. Each returns a dual JSON + rendered-markdown payload.

Prompts — slash workflows

/find-and-vet-agent (flagship) · /vet-agent · /compare-agents · /prepare-x402-call · /explore-registry. prepare-x402-call lays out the exact x402 flow and stops before signing — this server holds no keys.

Quickstart

One-command MCP setup (Claude Code):

npx -y stellar-agent-search@0.1.0 setup --client claude --scope user --handshake

This downloads the package, registers a version-pinned npx -y stellar-agent-search@0.1.0 mcp stdio launch through Claude Code's own CLI, then performs a real MCP initialize + tools/list handshake. It is idempotent: rerun with --check --handshake to verify without changing config, or use --dry-run to preview the registration. Cursor and Codex examples, config paths, and scope limitations are in docs/getting-started.md. Manual configs for other clients remain in docs/integration.md.

Optionally install the skill first — the usage guide your agent reads before it calls anything:

npx skills add berkingurcan/stellar-agent-search --skill mcp

Terminal (human CLI):

npx -y stellar-agent-search@0.1.0 find "web scraper" --x402       # discover
npx -y stellar-agent-search@0.1.0 profile 10                       # full profile for agent 10
npx -y stellar-agent-search@0.1.0 rank "scraping agents" --json    # rank + fail-closed contract-probe status, machine-readable
npx -y stellar-agent-search@0.1.0 services --x402                  # declared paid-endpoint candidates
npx -y stellar-agent-search@0.1.0 doctor                           # self-check: env, explorer, RPC, bounded read path
npx -y stellar-agent-search@0.1.0 setup --client cursor --scope project --dry-run  # preview client config

New here? Start with docs/getting-started.md.

Remote endpoint status

The intended hosted URL is https://mcp.stellar8004.com/mcp. The Worker, transport tests, routing, and hardening are implemented, but the route has not been deployed: /mcp currently falls through to the landing site and returns 404. Deployment remains deliberately blocked until the Cloudflare rate-limit namespace is replaced from its sentinel value and a live canary proves that the original caller identity is preserved through the Service Binding. Do not configure a remote MCP client against that URL yet.