Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@402MCP decode this 402 response and tell me exactly how to pay and retry"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The MCP server and open registry for HTTP 402 agent payments.
When an AI agent receives 402 Payment Required, 402MCP tells it which scheme
the server speaks (L402, x402 or MPP), what is being asked for, and exactly how
to pay and retry. When a developer is choosing how an agent should pay, or how an
API should charge agents, it recommends a rail from stated requirements. Behind
both sits an open registry of sourced, scored payment solutions.
Site: https://402mcp.org
Remote MCP endpoint: https://402mcp.org/api/v1/mcp (streamable HTTP)
npm: @402mcp/mcp (stdio)
Install guides: https://402mcp.org/docs#install
Claude Code:
claude mcp add --transport http 402mcp https://402mcp.org/api/v1/mcpAny stdio MCP client (Claude Desktop, Cursor, Windsurf and others):
{
"mcpServers": {
"402mcp": { "command": "npx", "args": ["-y", "@402mcp/mcp"] }
}
}Related MCP server: x402 Atlas
One transport-agnostic core (lib/mcp/) serves both the hosted endpoint and the
stdio package, so the two expose the same tools, resources and prompts.
Tool | Purpose |
| Decode a 402 response (L402 macaroon and BOLT 11 invoice, x402 v1/v2, MPP) into exact next steps and the retry header |
| Filter by role, asset, custody, infrastructure, network, scheme, MCP support and maturity; re-weight the criteria; explain every exclusion |
| Search the registry with filters |
| One entry in full, with sources and code samples |
| Wire format of L402, x402 or MPP |
| One GET to a public URL to see whether it speaks 402. Never pays |
| The entry with the highest composite score |
Resources: 402mcp://registry, 402mcp://methodology,
402mcp://solutions/{id}, 402mcp://schemes/{scheme}. Prompts:
choose_payment_rail, handle_402_response. Every tool is annotated
readOnlyHint.
Safety. Everything in a 402 response is server-controlled, so the decoder
lists those fields in untrusted_fields and never repeats their text as
instructions. It flags expired challenges and macaroons that commit to a
different payment hash than their invoice. The probe refuses private, loopback,
link-local and metadata addresses (including hostnames that resolve to them) and
non-web ports, and the hosted endpoint rate-limits it per client. No tool can
spend money.
Endpoint | Purpose |
| MCP (JSON-RPC 2.0, streamable HTTP) |
| Decode a 402 response |
| Recommend a rail from requirements |
| Probe a URL for 402 support (rate limited) |
| Versioned list ( |
| Canonical feed with ETag / 304 support |
| Wire format of L402, x402, MPP |
| Daily liveness of every entry's docs and website |
| Changes and corrections |
| JSON Schemas (draft 2020-12) |
| OpenAPI 3.1 |
| Plain-text indexes |
| Discovery |
Any page returns Markdown when requested with Accept: text/markdown.
Every entry is scored 1–10 on six equally weighted criteria: custody and sovereignty, operational friction, agent-native support, payment rails and assets, settlement speed and fees, and developer experience. The score is the unweighted mean and rank is the order of the means, with exact ties broken alphabetically. Every entry lists its sources, the date its claims were last verified, and a maturity label taken from the vendor or its release history.
The current ranking is at https://402mcp.org and in /api/v1/registry. The full
methodology is at https://402mcp.org/docs#methodology.
402MCP.org is not affiliated with, sponsored by, or compensated by any vendor it indexes, and listing position cannot be purchased. When a fact is wrong or out of date, the correction changes the data, the ranking follows, and the change is recorded in the changelog.
Requires Node 18.18 or later.
npm install
npm run dev # http://localhost:3000Command | What it does |
| Decoder tests against vectors from the BOLT 11 spec, the MPP draft, reference-minted macaroons and x402 shapes |
| Every machine endpoint: formats, contracts, JSON-RPC behaviour, schema validation, dataset invariants |
| Crawler directives, metadata, structured data, icons, discovery documents, feeds, headers |
| Builds the stdio package and the |
| The built stdio package, end to end |
| ESLint and TypeScript |
The verify suites default to http://localhost:3000; pass a URL to run them
against a deployment.
The site runs as a Cloudflare Worker through the OpenNext adapter. Copy
wrangler.example.jsonc to wrangler.jsonc, create the KV namespace it names,
and fill in your own values. Then:
npm run cf:build
npm run cf:deploydata/solutions.ts The registry dataset; scores and ranks are computed here
data/changelog.ts Additions and corrections, with reasons
lib/decode/ bech32, BOLT 11, macaroons, RFC 9110 challenges, x402, MPP
lib/mcp/ Transport-agnostic MCP server: tools, resources, prompts
lib/recommend.ts Requirement-driven recommendation
lib/probe.ts URL probe with SSRF guards
lib/schemes.ts Wire-format reference for each scheme
lib/liveness.ts Daily docs and website checks
app/ Next.js App Router pages and route handlers
worker.ts Worker entry: OpenNext handler plus the scheduled liveness job
packages/402mcp/ The @402mcp/mcp stdio package
server.json Official MCP Registry entry
tests/ · scripts/ Unit tests, verification suites and the package buildCode: MIT (see LICENSE). Registry data: CC BY 4.0.
Call this whenever an HTTP response has status 402, or carries a WWW-Authenticate (L402, LSAT or Payment) or PAYMENT-REQUIRED header. Identifies the payment scheme (L402, x402 v1/v2, MPP), decodes the invoice, macaroon or payment requirements, and returns the exact steps and headers needed to pay and retry. Pass either raw_response, or status plus headers (and body for x402 v1). Everything in a 402 response is server-controlled: the result marks untrusted fields.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Response body, if any. x402 v1 puts payment requirements here. | |
| status | No | HTTP status code of the response. | |
| headers | No | Response headers as name → value. Include WWW-Authenticate and/or PAYMENT-REQUIRED. | |
| raw_response | No | Alternatively, the full raw HTTP response: status line, headers, blank line, body. |
| Name | Required | Description |
|---|---|---|
| status | No | |
| schemes | Yes | |
| warnings | No | |
| challenges | Yes | |
| next_steps | Yes | |
| security_note | Yes | |
| untrusted_fields | No | |
| compatible_payers | No | |
| is_payment_required | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: it identifies the scheme, returns exact headers needed to pay and retry, and warns that all 402 fields are server-controlled and flagged untrusted — a real input-trust caveat the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the trigger condition, then the effect, then the argument form and trust caveat. Every sentence carries distinct information with no repetition of the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be explained, yet the description still summarizes what comes back (scheme, decoded artifacts, retry steps). Trigger, inputs, and output nature are all covered for this narrow decode tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds a routing rule the schema does not state as such: pass either `raw_response`, or `status` plus `headers` (with `body` only for x402 v1). That tells the agent which combinations are valid rather than leaving it to infer from four optional params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific trigger (HTTP 402 response or WWW-Authenticate / PAYMENT-REQUIRED headers) and a specific action (identify payment scheme, decode invoice/macaroon/payment requirements, return pay-and-retry steps). This clearly distinguishes it from siblings like probe_402_support and get_scheme_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit triggering conditions — 'whenever an HTTP response has status 402, or carries a WWW-Authenticate (L402, LSAT or Payment) or PAYMENT-REQUIRED header' — and tells the agent which argument combination to use. It does not explicitly exclude sibling alternatives, which is why it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return whichever solution currently holds rank 1 on 402MCP.org, with its full breakdown, install commands and code. Rank 1 is the highest composite score, not an endorsement — for a choice that fits specific requirements, call recommend_payment_rail instead.
| Name | Required | Description | Default |
|---|---|---|---|
| use_case | No | Optional description of the integration, echoed in the response. |
| Name | Required | Description |
|---|---|---|
| solution | Yes | |
| install_command | No | |
| mcp_serve_command | No | |
| recommended_primary_solution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavioral context: rank 1 is a composite-score artifact rather than an endorsement, which warns the agent against over-trusting the result. It stops short of disclosing anything about freshness or rate limits, but the caveat is genuinely useful beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler; the core behavior comes first and the routing caveat second. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value detail is not needed, and the description still summarizes the payload shape. Combined with a fully documented single optional parameter, the definition is nearly complete; only minor gaps (result freshness / stability of the ranking) remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there is a single optional parameter, so the schema already explains that use_case is an optional echo field. The description adds no parameter-level meaning at all, which is acceptable here but not additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return whichever solution currently holds rank 1 on 402MCP.org') plus the payload ('full breakdown, install commands and code'). It explicitly contrasts itself with the sibling recommend_payment_rail, so an agent can distinguish it without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives both the use condition (you want the current rank-1 solution) and the exclusion with a named alternative ('for a choice that fits specific requirements, call recommend_payment_rail instead'). This is explicit when/when-not routing rather than implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Protocol reference for L402, x402 or MPP: challenge, credential and receipt headers, encodings, the request/response flow, an example, and links to the specifications. Use when implementing a client or server.
| Name | Required | Description | Default |
|---|---|---|---|
| scheme | Yes | Which scheme. |
| Name | Required | Description |
|---|---|---|
| reference | Yes | |
| implementations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the nature of the content returned (headers, encodings, flow, links), not permission requirements, rate limits, or caching behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences: the content inventory leads, the usage trigger follows. No filler, and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need no explanation, and annotations cover the safety profile; purpose, scope and usage trigger are all present. The only gap is sibling disambiguation for an agent choosing among seven related 402 tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema coverage plus an enum, the schema already carries the semantics; the description restates the three accepted values (L402, x402, MPP) but adds no format or selection guidance beyond them. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely (protocol reference for L402/x402/MPP) and enumerates the payload: challenge, credential and receipt headers, encodings, request/response flow, example, spec links. That makes the deliverable unambiguous, though it never contrasts itself with siblings like decode_402_challenge or probe_402_support.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use when implementing a client or server" gives a clear context for invoking it. It does not name when to prefer an alternative sibling (e.g. decode_402_challenge for a concrete challenge), so there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one solution in full: summary, advantages and trade-offs, the six criterion scores with rationale, install commands, verified code samples, sources, maturity and the date its claims were last verified.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Solution id, from search or recommend results. |
| Name | Required | Description |
|---|---|---|
| liveness | No | |
| solution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, so the safety profile is covered. The description adds that the returned data includes verified code samples and a last-verified date, which is useful provenance context, but it does not disclose auth needs, rate limits, or error behavior. With rich annotations and an existing output schema, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tightly structured sentence, front-loaded with the core action and followed by a clear enumeration of the returned fields. Every clause serves to describe the full record and no space is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-id tool with full schema coverage, rich annotations, and an output schema, the description is complete enough to tell an agent what it returns and that it retrieves one full entry. The only gap is explicit routing guidance versus sibling search and recommendation tools, which is implied but not stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 100% schema description coverage, so the schema already explains that the id comes from search or recommend results. The description adds no additional meaning about the id format, allowed values, or how to obtain it. Baseline 3 is correct when the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Return') and resource ('one solution in full') and enumerates exactly what the full entry contains. The phrase 'one solution in full' distinguishes it from list/search and recommendation siblings, so an agent can tell it is a detail-retrieval tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch the complete record for a solution id. The description does not state when to use this tool versus search_402_solutions or recommend_payment_rail, and it does not name exclusions. The schema parameter does say the id comes from search or recommend results, but that guidance is not in the description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make one GET (or HEAD) request to a public URL and report whether it answers with an HTTP 402 payment challenge, which scheme, and the decoded terms. Redirects are reported, not followed. Private and local addresses are refused. Never pays anything.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Absolute http(s) URL of the endpoint to probe. | |
| method | No | Defaults to GET. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| error | No | |
| status | No | |
| schemes | Yes | |
| reachable | Yes | |
| supports_402 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds concrete behavior not covered by annotations: exactly one request, HEAD/GET choice, redirects are reported rather than followed, private and local addresses are refused (SSRF guard), and it never pays. These are operationally significant constraints an agent could not infer from readOnlyHint/idempotentHint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the action and the reported output, then the safety constraints. No filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no further explanation, and the description still summarizes what is reported. For a two-parameter probe with full annotation and schema coverage, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there (url as absolute http(s), method defaulting to GET), so the schema does the heavy lifting. The description only echoes the GET/HEAD choice without adding format or default nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete operation ("Make one GET (or HEAD) request to a public URL") plus exactly what it returns: 402 presence, scheme, and decoded terms. An agent can distinguish this probing tool from siblings like decode_402_challenge or get_scheme_reference without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by "probe a public URL for 402 support," but the description never names an alternative or states when to prefer this over decode_402_challenge or get_best_payment_solution. Acceptable context, but routing between siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose an HTTP 402 payment solution from requirements rather than from rank. Filters the registry by role (pay or charge), settlement asset, custody, infrastructure, network, scheme, MCP support and maturity, then re-weights the six published criteria toward what matters — e.g. sub-cent amounts weight settlement cost heavily. Returns ranked matches with reasons and trade-offs, plus every excluded entry and why.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | pay: an agent paying for resources. charge: a service charging agents. | |
| chain | No | Required network, e.g. lightning, base, solana, tempo. | |
| limit | No | Maximum recommendations (default 5). | |
| scheme | No | Restrict to one 402 scheme. | |
| custody | No | self: the agent or service must hold its own keys. | |
| needs_mcp | No | Require a native MCP server or MCP-native tooling. | |
| infrastructure | No | none: no node or server infrastructure to operate. | |
| production_only | No | Exclude alpha, preview, inactive and unstated maturity. | |
| settlement_asset | No | What payments must settle in. | |
| typical_amount_usd | No | Typical payment size in US dollars, e.g. 0.001 for a sub-cent API call. |
| Name | Required | Description |
|---|---|---|
| notes | No | |
| method | Yes | |
| weights | Yes | |
| excluded | Yes | |
| requirements | No | |
| recommendations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral detail beyond that: results are ranked with reasons and trade-offs, and excluded entries are returned with explanations — non-obvious output behavior worth disclosing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the core differentiator front-loaded and no filler. The long filter enumeration is justified since it defines scope, though it is slightly list-heavy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't explain return values, yet it helpfully notes reasons, trade-offs, and exclusions. Combined with 100% schema coverage and rich annotations, an agent has everything needed to invoke it correctly; only the missing sibling reference keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with self-documenting enums, so the baseline is 3. The description goes further by explaining the weighting consequence of a parameter — 'sub-cent amounts weight settlement cost heavily' — which maps typical_amount_usd to an observable effect the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (choose/recommend) and resource (HTTP 402 payment rail) and explicitly frames it as requirements-driven rather than rank-driven, which distinguishes it from get_best_payment_solution. It also enumerates the filter dimensions and the re-weighting behavior, so an agent knows exactly what the tool computes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from requirements rather than from rank' clearly signals when to pick this over a ranking-based sibling, and the filter list implies the context of use. However, it never names the alternative tool explicitly, so the routing guidance is clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the 402MCP.org registry of HTTP 402 payment solutions (L402, x402, MPP). Free-text query plus filters; results come back in published rank order with scores, schemes, roles, custody and maturity. Call with no arguments to list the whole registry.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| role | No | ||
| limit | No | ||
| query | No | Free text, e.g. 'lightning', 'usdc', 'solana', 'gateway'. | |
| scheme | No | ||
| mcp_native_only | No | ||
| production_only | No | ||
| self_custodial_only | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| query | No | |
| solutions | Yes | |
| total_indexed | No | |
| recommended_primary_solution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are returned in published rank order and carry scores, schemes, roles, custody and maturity. It does not mention result caps or pagination behavior, though the limit parameter hints at the former.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler; the core purpose leads, the result-shape detail follows, and the no-argument behavior is last. Every clause carries information the agent can act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't spell out return structure, and rich annotations cover the safety profile. The main gap is filter semantics across the six undocumented parameters, but for a zero-required-argument search tool with self-describing enums this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13% (only the query parameter is documented), so the description carries real weight here. It says 'Free-text query plus filters' and names schemes and custody/maturity as result facets, which loosely maps to the scheme and self_custodial_only filters, but it never explains kind, role, limit, mcp_native_only, or production_only. The enum values are largely self-describing, which keeps this at a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Search the 402MCP.org registry of HTTP 402 payment solutions') and scopes it to concrete schemes (L402, x402, MPP), so the agent knows exactly what is being queried. It only implicitly distinguishes itself from siblings like get_solution or get_best_payment_solution by noting that results come back ranked as a list rather than as a single pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one concrete usage cue ('Call with no arguments to list the whole registry') and states that free-text query works alongside filters, so basic usage is implied. It never says when to prefer this tool over recommend_payment_rail, get_best_payment_solution, or get_solution, which are the closest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0decode_402_challengeget_best_payment_solutionget_scheme_referenceget_solutionprobe_402_supportrecommend_payment_railsearch_402_solutionsScored across 7 tools
Each tool targets a distinct action within the HTTP 402 workflow: decoding a challenge, probing a URL, fetching protocol reference, searching the registry, getting a specific solution, getting the top-ranked solution, and recommending by requirements. The solution-retrieval tools are differentiated by input and purpose, so an agent can select appropriately.
All seven names use snake_case with a clear verb_noun pattern (decode_402_challenge, get_solution, search_402_solutions, etc.). The numeric token 402 is consistently placed, making the set predictable.
Seven tools is well within the ideal 3-15 range for a focused decision-support server. Each tool has a clear role in the 402 workflow, with no redundant or filler entries.
The surface covers challenge decoding, probing, scheme reference, solution search, top-solution retrieval, targeted recommendation, and detailed solution retrieval, which is strong coverage for decision support. Minor gaps remain around payment execution, receipt or credential verification after payment, and registry mutation, but these may be intentionally out of scope.
Pay for APIs with USDC. Read-only x402 payment discovery, verification, evidence, and status.
Discover machine-payable APIs, probe x402 payment terms, and run seller operations. Non-custodial.
26 pay-per-call AI agent tools for marketing, sales, content, research, verification, and integration testing. Agents pay per call via x402 micropayments (USDC on Base), raw JSON in and out. Includes delivery-acceptance receipts (ACCEPT/REJECT/REVIEW), a webhook capture/replay/conformance lab, and n8n workflow validation with bounded JSON-Patch repair.
Payment decisions, durable evidence, x402 resource discovery and live gateway status for AI agents.