Documentation menu

MCP server reference

Every tool, resource and prompt of the Settlens MCP server with its inputs and outputs, the stdio and Streamable HTTP transports, authentication, limits and errors.

In short

The Settlens MCP server has 8 read-only tools over stdio and Streamable HTTP: 6 offline tools, public at https://settlens.com/mcp, and 2 passive network tools that need a token there. evaluate_payment_requirements answers pay, review or do_not_pay; pay needs pay_to, assets, networks and max_amount in the policy.

On this page

The Settlens MCP server lets an AI agent check an x402 payment request before it pays, and verify payments, reports and attestations, from any Model Context Protocol client. This reference is generated from the server code of Settlens 0.5.0 when the site is built: the tables are the server's own tools/list, resources/list and prompts/list answers, and every example response was produced by it.

For an overview and setup in one page, see the MCP server. For the reasoning behind the policy fields, read the agent spending policy guide and why agents should verify before paying. To try evaluate_payment_requirements without a client, use the x402 payment request checker in your browser.

Server name: settlens (Settlens), version 0.5.0
Protocol revisions: 2025-06-18, 2025-03-26 and 2024-11-05; 2025-06-18 when the client asks for another one
Transports: stdio (settlens mcp) and Streamable HTTP at https://settlens.com/mcp
Capabilities: tools, resources and prompts, none of which change at runtime
Tools: 8: 6 offline, 2 network (passive only)
Never: signs, pays, settles, broadcasts, holds funds or needs a wallet or payment key

Connect

The remote endpoint needs nothing installed. The local server runs from the Settlens source, which pilot participants receive (Node.js 20.19 or newer, then npm ci --ignore-scripts).

Where each tool is available
Setup	Command or URL	Tools
Remote, public	`https://settlens.com/mcp`	6 offline tools
Remote, with token	`https://settlens.com/mcp` + `Authorization: Bearer <token>`	All 8
Local stdio	`node src/cli.js mcp`	All 8, with no destination restriction
Container	`docker run -i --rm settlens:local mcp`	All 8 (stdio; keep `-i`)

ShellClaude Code

# Remote, offline tools
claude mcp add --transport http settlens https://settlens.com/mcp

# Remote, with the network tools
claude mcp add --transport http settlens https://settlens.com/mcp \
  --header "Authorization: Bearer ${SETTLENS_API_TOKEN}"

# Local stdio, every tool
claude mcp add settlens -- node /absolute/path/to/settlens/src/cli.js mcp

JSONclaude_desktop_config.json (local stdio)

{
  "mcpServers": {
    "settlens": {
      "command": "node",
      "args": [
        "/absolute/path/to/settlens/src/cli.js",
        "mcp"
      ]
    }
  }
}

Claude Desktop reads that file from ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows; restart it after editing. On Windows, escape backslashes in the path ("C:\\settlens\\src\\cli.js").

Agent workflow

The server sends these instructions to the client in its initialize result, so a capable client tells the model when to call it:

Settlens checks x402 payment requests before you pay. It never pays, never signs and never needs a wallet or key. On every HTTP 402 response, call evaluate_payment_requirements with the PAYMENT-REQUIRED header value, the URL you requested (resource_url) and your spending policy (at least pay_to, assets, networks and max_amount) BEFORE paying. Never pay when the decision is do_not_pay. When it is review, show the summary and reasons to the human and ask for explicit approval before paying. When it is pay, pay only with one of the entries listed in acceptable.

Request the paid URL without any payment header.
On HTTP 402, read the PAYMENT-REQUIRED header.
Call evaluate_payment_requirements with payment_required (the raw header value), resource_url (the exact URL requested) and policy.
do_not_pay: never pay. review: show the summary and reasons, wait for explicit approval. pay: pay with one entry of acceptable only, using your own wallet tooling.

Enforce the decision outside the model

The decision is advice to the model. If your agent can pay, make the payment tool itself refuse unless the last decision for that URL was pay and the chosen option is in acceptable.

Decision rules

A PaymentRequired usually advertises several options in accepts, and the agent pays with one. The server's terms are judged as a whole (decoding, the official @x402/core 2.28.0 schema, the V2 shape, the resource.url binding, well-formed options, duplicates, authorization windows). The policy is applied to each option:

An option is acceptable when it is well formed and satisfies every policy constraint you set.
policy.acceptable_option (high) passes when at least one option is acceptable. Its message counts the rejected options by constraint.
The per-constraint checks policy.scheme, policy.network, policy.recipient, policy.asset and policy.maximum_amount only summarize: pass when every option complies, warn (severity info) when some do not, fail when none does. They never decide on their own.

The decision, for evaluate_payment_requirements and scan_endpoint alike:

Any failing check of severity high or critical (policy.acceptable_option included, the per-constraint summaries excluded): do_not_pay, and acceptable is empty.
Otherwise, any failing or warning check other than the per-constraint summaries: review. A missing resource_url lands here, because binding.resource_url becomes a medium warning.
Otherwise, when no option could be evaluated against the policy: review.
Otherwise, when the policy does not set pay_to, assets, networks and max_amount: review, with a reason naming the missing fields.
Otherwise: pay, with an option from acceptable only.

x402 over HTTP only

The tools evaluate x402 over HTTP. x402 carried over MCP itself, where a paid tool answers with isError and a PaymentRequired in structuredContent and the client pays in _meta["x402/payment"], is not supported. The transport's own example names an mcp:// resource: schema.payment_required rejects it, because Settlens requires an absolute http(s) resource.url where the x402 specification sets no scheme, so the decision is do_not_pay. resource_url accepts only http(s) URLs.

The CLI keeps the stricter rule meant for merchants: in settlens scan, every advertised option must be within the configured policy (see configuration).

The policy object

Optional on both tools that take it; no other fields are accepted. Atomic units: USDC has 6 decimals, so "10000" is 0.01 USDC.

policy fields
Field	Type and rules	Description
max_amount	string digits only (integer string); at most 78 characters	Maximum amount you accept to pay, as an integer string in the asset's atomic units (USDC has 6 decimals: "10000" = 0.01 USDC). Set assets too, so the unit is fixed.
networks	array of string 1 to 32 items; each item: non-empty, at most 128 characters	Allowed CAIP-2 networks, for example ["eip155:8453"] for Base mainnet.
schemes	array of string 1 to 32 items; each item: non-empty, at most 64 characters	Allowed x402 schemes, for example ["exact"].
pay_to	array of string 1 to 32 items; each item: non-empty, at most 128 characters	Allowed recipient addresses (payTo) you have reviewed. EVM 0x addresses are compared case-insensitively, other formats (Solana base58, ...) exactly.
assets	array of string 1 to 32 items; each item: non-empty, at most 128 characters	Allowed tokens (asset): contract addresses or mints you have reviewed, for example ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"] for USDC on Base. EVM 0x addresses are compared case-insensitively, other formats (Solana mints, ...) exactly.

The same values are validated as a configuration file policy; a value the schema accepts but that validation rejects makes the call fail with isError. With several assets, max_amount applies to each in its own decimals: list only assets with the same decimals.

Tools

Tools at a glance
Tool	Mode	Remote access	Summary
evaluate_payment_requirements	offline	public	Should I pay this x402 request?
verify_payment_signature	offline	public	Verify an exact EVM payment signature
verify_solana_transaction	offline	public	Verify Solana signatures and payment instructions
verify_report	offline	public	Verify a Settlens report
verify_attestation	offline	public	Verify a Settlens evidence attestation
list_checks	offline	public	List Settlens checks
scan_endpoint	network, passive	token	Passively scan an x402 endpoint
scan_facilitator	network, passive	token	Passively scan an x402 facilitator

Arguments use snake_case; URL arguments may not contain whitespace. A call whose arguments do not match the input schema is rejected with JSON-RPC error -32602 before the tool runs. Every successful result carries structuredContent, matching the tool's output schema, and the same JSON as one text content block.

`evaluate_payment_requirements`

Offline Should I pay this x402 request?

Call this on every HTTP 402 response BEFORE paying. Give it the PAYMENT-REQUIRED header value, the URL you requested and your spending policy (pay_to, assets, networks and max_amount, optionally schemes). Offline: it decodes and validates the x402 V2 payment request with the official @x402/core schema, checks that it is bound to the URL you requested, validates every payment option (scheme, CAIP-2 network, amount, asset, payTo, timeout window) and applies your policy to each option, since you pay with only one. Returns decision 'pay', 'review' (ask the human first) or 'do_not_pay' (never pay), the reasons, and the payment options that satisfy your policy (acceptable). It does not check balances, settlement or what the token at asset does, and it never pays.