Skip to main content
By the end of this page you will have connected an MCP client to the Rail402 discovery server and understand its two tools: one that searches the Bazaar and one that pays a discovered resource under a required cap. This uses @rail402.dev/mcp-discovery (bin rail402-mcp). It puts the discover, pay, retry loop behind Model Context Protocol tools, so an agent in Claude Code, Cursor, or any MCP client can find and buy a Stellar service with no pre-built integration.

​
The two tools

search_stellar_resources

Natural-language search over the Bazaar. Pays nothing. Returns structured results with price, input schema, and settled-usage counts.

pay_and_call

Discover the price, pay, and return the resource result. Refuses to run without a spend cap.
Both tools declare strict JSON input and output schemas, and every rejection carries a machine-readable code with a non-null reason, so an agent can reason about failure instead of parsing prose.

​
search_stellar_resources

Takes a query in natural language, plus optional filters (network, type of http or mcp, a maxPrice atomic-unit ceiling, and a limit). It returns the ranked matches with their price, asset, payTo, input schema, and a settled-payer usage count. Nothing is paid.

​
pay_and_call

Takes the resource URL exactly as search returned it and a maxAmount, the most you authorize for this one call, in atomic units. maxAmount is mandatory: the tool never pays an unbounded amount. For an MCP-tool resource, pass its toolName and the call switches from HTTP to an MCP call. The cap binds in the same selector that signs, so it is checked against the price actually paid.
maxAmount is required. A pay_and_call with no cap is refused with mcp_budget_required and nothing is paid. Set an operator ceiling too when the server runs unattended, so every paid call stays below whatever an agent asks for.

​
Run it locally over stdio

An agent runtime spawns the server over stdio, which is the default transport. Add a signing secret to enable paying; omit it for a search-only server that cannot spend.
Point your MCP client at the binary. A typical stdio client config:
Without --secret the server still exposes search_stellar_resources, so an agent can discover services without any ability to spend. Add the secret only when you want it to pay.

​
Or use the hosted server over HTTP

A hosted testnet instance runs over Streamable HTTP. Point an HTTP-capable MCP client at it:
To run your own HTTP server instead of stdio, add --http:

​
Reading a failure

Every rejection is { code, reason, retryable }. Two codes matter most for an agent deciding whether to retry: The second is the one that matters: it is not retryable because money already moved, and the response still carries the transaction hash so the agent can see what it paid for. See Rejection reasons for the full set.

​
Run the loop end to end

The examples/mcp-agent-zero-integration project runs an agent that discovers a seller it has never heard of, pays it through these tools, returns the result, and then refuses an over-budget retry. It settles a real testnet transaction.

​
Next steps

Spend controls

The mandatory cap and the operator ceiling above it.

Discover services

The same search, from the SDK.

The rail402 CLI

The same loop from a terminal, with a bundled agent skill.

Bazaar

What gets catalogued and how.

​
When it fails

The MCP tools code every rejection with a non-null reason. The distinction between “no money moved, retry” and “money moved, do not retry” is spelled out in Rejection reasons.