Agent & MCP

Find what to pay for on Stellar. apps/agent is the agent-facing half of STELLARSIGHT: an MCP server that drops the Stellar Bazaar directly into an AI agent’s runtime. The agent searches the bazaar in natural language, reads a resource’s exact call contract, and then actually pays for it — the full discover → 402 → sign → retry → settle x402 loop happens inside a single tool call. No API key. No vendor account. No human in the loop. Just a wallet. This is RFP requirement 3.3.

File	What it is
`src/mcp-server.mjs`	MCP server over stdio (`@modelcontextprotocol/sdk` v1.30) exposing four tools
`src/pay.mjs`	Reusable x402 payment client — `payAndFetch(url, opts)`
`src/bazaar.mjs`	Fail-soft HTTP client for the discovery index (`/discovery/*`)
`src/cli.mjs`	Narrated terminal demo of the whole loop
`src/replay-guard.test.mjs`	`node:test` proof that replays and expired auth entries are refused with a reason

Testnet only. No relayer, no third-party channel service — the payment is signed locally with @x402/stellar and settled by the STELLARSIGHT facilitator on stellar:testnet.

Quick start

npm install
npm run setup                       # writes /.env with the funded testnet keys
npm run dev:all                     # facilitator :4021 · index :4022 · seller :4023

node apps/agent/src/cli.mjs "usd to brl exchange rate"

Everything here starts and degrades cleanly with the stack down. If the index or the seller is not reachable you get a coded rejection with an explanation, never a stack trace.

Wiring it into Claude

Claude Desktop — `claude_desktop_config.json`

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stellarsight": {
      "command": "node",
      "args": ["/absolute/path/to/repo/apps/agent/src/mcp-server.mjs"],
      "env": {
        "STELLAR_NETWORK": "stellar:testnet",
        "STELLAR_RPC_URL": "https://soroban-testnet.stellar.org",
        "INDEX_URL": "http://localhost:4022",
        "FACILITATOR_URL": "http://localhost:4021",
        "PAYER_SECRET": "S...."
      }
    }
  }
}

Claude Code

claude mcp add stellarsight -- node /absolute/path/to/repo/apps/agent/src/mcp-server.mjs

or in .mcp.json at the project root:

{
  "mcpServers": {
    "stellarsight": {
      "command": "node",
      "args": ["apps/agent/src/mcp-server.mjs"]
    }
  }
}

PAYER_SECRET and friends are read from the repo-root /.env when they are not in env, so the plain form above works once scripts/setup-testnet.mjs has run. Diagnostics go to stderr only — stdout is the JSON-RPC transport.

Tools

All four tools return both a JSON text block (for the model) and structuredContent (for the host). Every result is { ok: true, ... } or { ok: false, code, reason }. reason is never null on a rejection.

`stellarsight_search`

Ranked natural-language search over the bazaar. Each candidate carries the index’s _explain breakdown, so the ranking is auditable rather than a black box.

// input
{
  "query":    "string, required — what the agent needs",
  "limit":    "integer 1-50, optional (default 5)",
  "network":  "string, optional — CAIP-2 filter, e.g. stellar:testnet",
  "maxPrice": "string, optional — budget ceiling in atomic units"
}

// output
{
  "ok": true,
  "query": "usd to brl exchange rate",
  "items": [{
    "id": "http://localhost:4023/v1/fx/usd-brl",
    "url": "...", "serviceName": "stellarsight-fx", "description": "...", "tags": ["fx"],
    "type": "http", "network": "stellar:testnet", "scheme": "exact",
    "payTo": "G...", "asset": "C...", "maxAmountRequired": "100000",
    "settlements": 1,
    "score": 0.4982,
    "_explain": { "bm25": 3.51, "terms": [...], "matchedFields": [...], "quality": {...} }
  }],
  "partialResults": false,
  "pagination": { "limit": 5, "cursor": null },
  "source": "http://localhost:4022"
}

`stellarsight_browse`

Unranked catalogue listing. Use it to see what exists, or to enumerate one seller’s endpoints.

// input
{ "type": "http | mcp, optional", "payTo": "G..., optional",
  "network": "string, optional", "limit": "1-100, default 20", "offset": "integer, default 0" }

// output
{ "ok": true, "items": [ /* same summary shape as search, without score */ ],
  "total": 4, "limit": 20, "offset": 0, "source": "http://localhost:4022" }

`stellarsight_describe`

Full discovery metadata for one resource, flattened into a call-construction brief: every parameter with its type, whether it is required, and its description — so the agent can build a valid call with no external documentation.

// input
{ "id": "string, required — resource id from search/browse (url, or url#toolName for MCP)" }

// output
{
  "ok": true,
  "id": "http://localhost:4023/v1/fx/usd-brl",
  "resource": { "url": "...", "serviceName": "...", "description": "...", "tags": [...] },
  "type": "http", "network": "stellar:testnet", "scheme": "exact",
  "payTo": "G...", "asset": "C...", "maxAmountRequired": "100000",
  "routeTemplate": "/v1/fx/{pair}",
  "input":  { "type": "http", "method": "GET", "queryParams": {...} },
  "output": { "type": "json", "example": {...} },
  "parameters": [
    { "name": "pair", "in": "query", "type": "string", "required": true,
      "description": "Currency pair", "enum": null, "example": "USD/BRL" }
  ],
  "howToCall": { "tool": "stellarsight_pay", "url": "...", "method": "GET", "params": {...},
                 "methodHint": "Pass params as the query string (stellarsight_pay defaults to GET).",
                 "note": "..." },
  "source": "http://localhost:4022"
}

`stellarsight_pay`

The whole x402 loop in one call: request → 402 challenge → sign the Soroban auth entry with the operator’s PAYER_SECRET → retry with the payment header → return the unlocked body plus the settled transaction hash and its explorer link. Spends real testnet funds. Set maxPrice to cap it.

// input
{
  "url":       "string, required — absolute URL of the paid resource",
  "params":    "object, optional — query string for GET, JSON body for POST/PUT/PATCH",
  "method":    "GET | POST | PUT | PATCH | DELETE, optional (default GET)",
  "maxPrice":  "string, optional — spend ceiling in atomic units",
  "timeoutMs": "integer 1000-120000, optional (default 30000)"
}

// output
{
  "ok": true,
  "paid": true,
  "status": 200,
  "body": { "pair": "USD/BRL", "bid": 5.4312, "ask": 5.4389, "mid": 5.435 },
  "txHash": "9f2c…",
  "explorerUrl": "https://stellar.expert/explorer/testnet/tx/9f2c…",
  "payer": "G...", "network": "stellar:testnet",
  "amount": "100000", "asset": "C...", "payTo": "G...",
  "timings": { "challengeMs": 12, "signMs": 640, "settleMs": 2180, "totalMs": 2832 }
}

A free resource is not an error: it returns { ok: true, paid: false, body }. timings is always present, including on rejections — the UI reads it.

Error codes

Every rejection is { ok: false, code, reason } with a non-null, human-readable reason. Nothing throws out of a tool handler.

Code	Meaning	Typical fix
`STELLARSIGHT_CONFIG_MISSING`	`PAYER_SECRET` absent or not a valid `S...` seed	run `scripts/setup-testnet.mjs`, or set it in the MCP `env` block
`STELLARSIGHT_BAD_REQUEST`	malformed argument (empty url/query/id, non-integer `maxPrice`)	fix the argument named in the reason
`STELLARSIGHT_INDEX_UNREACHABLE`	the discovery index did not answer	start the stack (`npm run dev:all`) or set `INDEX_URL`
`STELLARSIGHT_INDEX_ERROR`	index answered non-2xx or non-JSON	check the index logs; the HTTP status is in the reason
`STELLARSIGHT_NO_RESULTS`	nothing matched the query or the filters	broaden the query, or raise `maxPrice`
`STELLARSIGHT_NOT_FOUND`	no resource with that id is registered	get a valid id from `stellarsight_search` / `stellarsight_browse`
`STELLARSIGHT_RESOURCE_UNREACHABLE`	the seller endpoint refused the connection	the seller is down, or the URL is wrong
`STELLARSIGHT_402_MALFORMED`	402 with no decodable `PAYMENT-REQUIRED` header and no `accepts` body	the seller is not speaking x402 v2
`STELLARSIGHT_UNSUPPORTED_NETWORK`	resource wants a network/scheme this agent is not configured for	testnet only; check `STELLAR_NETWORK`
`STELLARSIGHT_PRICE_EXCEEDS_BUDGET`	quoted price is above the caller’s `maxPrice`	raise `maxPrice`, or pick a cheaper resource
`STELLARSIGHT_SIGN_FAILED`	the Soroban auth entry could not be built or signed	check RPC reachability and the payer account
`STELLARSIGHT_INSUFFICIENT_BALANCE`	payer lacks the asset, or has no trustline	fund the payer / add the trustline
`STELLARSIGHT_REPLAY_REJECTED`	the payment authorization had already been consumed	sign a fresh payment; never reuse a header
`STELLARSIGHT_AUTH_EXPIRED`	the auth entry’s ledger bounds had passed	retry — signing is cheap
`STELLARSIGHT_SETTLE_FAILED`	facilitator returned `success: false` for another reason	the facilitator’s `errorReason` is quoted in the reason
`STELLARSIGHT_UPSTREAM_ERROR`	unexpected non-402 HTTP error, or an internal throw	read the reason; the HTTP status is included
`STELLARSIGHT_TIMEOUT`	the resource or index exceeded the timeout	raise `timeoutMs`

The enum is exported as ERROR_CODES from src/pay.mjs, and facilitator failure strings are mapped onto it deterministically by classifySettleFailure().

The terminal demo

node apps/agent/src/cli.mjs "usd to brl exchange rate"
node apps/agent/src/cli.mjs "an agent that reads invoices" --dry-run
node apps/agent/src/cli.mjs "usd to brl exchange rate" --max-price 200000 --limit 3

Four movements, narrated live:

QUERY             the natural-language ask, and the wallet behind it
SIGHTS TAKEN      ranked candidates with score meters and _explain breakdowns
BEARING FIXED     the chosen resource, its price, its payee
PAYMENT SETTLED   402 challenge · auth-entry signing · settled tx · explorer link
    UNLOCKED PAYLOAD  the data the agent just bought

Flag	Effect
`--dry-run`, `-n`	discovery and ranking only; never signs, never spends
`--max-price N`	refuse to pay above `N` atomic units
`--limit N`	number of candidates to sight (default 5)

Using the payment client directly

import { payAndFetch, ERROR_CODES } from './apps/agent/src/pay.mjs';

const res = await payAndFetch('http://localhost:4023/v1/fx/usd-brl', {
  params: { pair: 'USD/BRL' },
  maxPrice: '200000',
  onEvent: (e) => console.log(e.stage)   // request · challenge · signed · settled
});

if (!res.ok) console.error(res.code, res.reason);
else console.log(res.body, res.txHash, res.explorerUrl, res.timings);

payAndFetch never throws for a protocol or network failure — it resolves to a coded result.

Tests

node --test apps/agent/src/replay-guard.test.mjs

Proves that a replayed PAYMENT-SIGNATURE header and an expired authorization entry are both refused, each with a non-null reason and the right code, and that no rejection path in the client can produce a null reason. The first three tests are hermetic (local stub seller, throwaway keypair, no network). The fourth exercises the live facilitator and skips cleanly when it is not running.

Environment

Read from the repo-root /.env, overridable by process.env or the MCP env block.

Variable	Default	Used for
`STELLAR_NETWORK`	`stellar:testnet`	CAIP-2 network id passed to `createEd25519Signer`
`STELLAR_RPC_URL`	`https://soroban-testnet.stellar.org`	Soroban RPC for simulation/signing
`INDEX_URL`	`http://localhost:4022`	discovery index
`FACILITATOR_URL`	`http://localhost:4021`	facilitator (`/supported`, `/verify`, `/settle`)
`SELLER_URL`	`http://localhost:4023`	demo seller
`PAYER_SECRET`	—	the agent’s wallet; required for `stellarsight_pay`
`PAYER_PUBLIC`	—	display only
`ASSET_CODE`	`SXT`	display only

Protocol notes

Verified against the installed @x402/core@2.21 build, not assumed:

402 challenge arrives in the PAYMENT-REQUIRED response header (base64 JSON). STELLARSIGHT also accepts the same object in the JSON body, which is what several v2 servers emit.
The signed payload goes out as PAYMENT-SIGNATURE (x402 v2); STELLARSIGHT mirrors it onto X-PAYMENT so v1-shaped sellers work unchanged.
Settlement comes back in PAYMENT-RESPONSE / X-PAYMENT-RESPONSE as { success, errorReason, transaction, network, payer }.
Bazaar extension status rides on EXTENSION-RESPONSES (base64 JSON) and is surfaced as extensions.bazaar on the result.

Get started

Guides

Reference

Security

Evidence

Upstream

Quick start

Wiring it into Claude

Claude Desktop — `claude_desktop_config.json`

Claude Code

Tools

`stellarsight_search`

`stellarsight_browse`

`stellarsight_describe`

`stellarsight_pay`

Error codes

The terminal demo

Using the payment client directly

Tests

Environment

Protocol notes

​Quick start

​Wiring it into Claude

​Claude Desktop — claude_desktop_config.json

​Claude Code

​Tools

​stellarsight_search

​stellarsight_browse

​stellarsight_describe

​stellarsight_pay

​Error codes

​The terminal demo

​Using the payment client directly

​Tests

​Environment

​Protocol notes

Quick start

Wiring it into Claude

Claude Desktop — `claude_desktop_config.json`

Claude Code

Tools

`stellarsight_search`

`stellarsight_browse`

`stellarsight_describe`

`stellarsight_pay`

Error codes

The terminal demo

Using the payment client directly

Tests

Environment

Protocol notes