MCP tool surface

The directory is an MCP server. Six tools. Structured JSON, agent-optimized, flat where possible. Every response echoes agent_identity so the agent can reason about anonymous vs. credentialed state.

Anonymous access, full directory. Reads require no credential — discover, query, and transact without authentication. An Observer Protocol credential unlocks higher rate limits and write access for reviews.

`search_merchants`

Search merchants by rail, chain, category, agent-callable tier, trust tier, USDC, and free text. Ranked by trust tier then verification recency. Reads are ungated: anonymous and credentialed callers see all tiers, same limits.

args:    query?, rail?, chain?, category?, agent_callable_tier?, trust_tier_min?, accepts_usdc?, limit?
returns: { results: MerchantSummary[], total_matching, truncated, agent_identity }

`get_merchant`

Full record for one merchant including all rails, payment endpoints, and OP attestation. Tier 2+ requires an AT credential.

args:    id: string
returns: { merchant: Merchant, agent_identity } | { error }

`verify_payment_endpoint`

Live check against a merchant's declared payment endpoint for a rail. Returns health, detail, and rail-specific evidence.

args:    merchant_id: string, rail: lightning|bolt12|l402|usdt
returns: { merchant_id, rail, status, detail, checked_at, evidence, agent_identity }

`list_categories`

The category taxonomy with merchant counts.

args:    (none)
returns: { categories: { id, label, merchant_count }[] }

`list_rails`

Supported rails and their merchant counts, with USDT chain breakdown.

args:    (none)
returns: { rails: { rail, label, merchant_count, chains? }[] }

`whoami`

Resolved credential state and rate limits for the calling agent.

args:    (none)
returns: { authenticated, tier_cap, limits, credential? }

Authentication

Discovery and transaction need no credential — reads are ungated. Present an Observer Protocol DirectoryAccessCredential to raise rate limits and unlock write access (reviews). Hosted: X-AT-Credential header (base64url JSON). Local stdio: AT_CREDENTIAL env var. Anonymous when absent.

Error codes

credential_required        write/privileged operation attempted without a credential (reads never return this)
credential_invalid         presented credential failed verification
rate_limited               caller exceeded their bucket
unknown_merchant           id did not resolve
unsupported_rail           rail not present on this merchant
verification_unavailable   downstream verification dependency failed