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., "@paybot-mcp pay 0.05 USDC to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e for API access"
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.
MCP server for PayBot — payment tools for AI agents via the Model Context Protocol.
npm install paybot-mcp paybot-sdkRelated MCP server: remit.md MCP Server
PAYBOT_API_KEY is required — without it every tool call fails with a 401. The fastest way to get a key is one PayBotClient.signup() call (from paybot-sdk) against the hosted facilitator at https://api.paybotcore.com:
node -e "import('paybot-sdk').then(async ({ PayBotClient }) => {
const a = await PayBotClient.signup('you@example.com', 'a-strong-password', { botId: 'my-agent' });
console.log(a.apiKey); // pb_live_... — printed ONLY once, save it now
})"This single call registers your operator account, creates the API key, and registers the bot (botId). Put the printed key into PAYBOT_API_KEY in the MCP config below, and reuse the same bot id as PAYBOT_BOT_ID.
Notes:
The key is printed only once — store it securely; it cannot be retrieved later.
Because signup() already registered your bot, calling the paybot_register tool with the same bot id returns 409 ALREADY_EXISTS. Use paybot_register only for additional bots.
Full auth flow (login, extra API keys, self-hosted facilitators): see the paybot-sdk README → Get your API key.
Add to claude_desktop_config.json:
{
"mcpServers": {
"paybot": {
"command": "npx",
"args": ["paybot-mcp"],
"env": {
"PAYBOT_API_KEY": "pb_...",
"PAYBOT_FACILITATOR_URL": "https://api.paybotcore.com",
"PAYBOT_BOT_ID": "my-agent"
}
}
}
}{
"mcpServers": {
"paybot": {
"command": "npx",
"args": ["paybot-mcp"],
"env": {
"PAYBOT_API_KEY": "pb_...",
"PAYBOT_BOT_ID": "my-agent"
}
}
}
}Variable | Description | Default |
| PayBot API key (see Get your API key) | (required) |
| Facilitator server URL |
|
| Default bot identifier |
|
| Wallet private key for real payments | (optional) |
| Register the governed mock demo tools ( |
|
If PAYBOT_API_KEY is unset or empty, the server still boots (so the MCP handshake succeeds) but prints a warning to stderr at startup, and every tool call will fail with an authentication error until a key is configured. Omitting PAYBOT_WALLET_KEY keeps the underlying SDK in mock mode (no on-chain settlement).
Tool | Description |
| Make a payment (USDC by default; supports alternate tokens + idempotency) |
| Check trust level, spending limits, and remaining budget |
| View recent payment history and audit events |
| Register a new bot with the facilitator (optional idempotency key) |
| Discover supported networks and tokens (offline, no API key) |
| Extended facilitator health (status/version/uptime + extras) |
| Set per-transaction / daily / hourly limits and a recipient allowlist |
| Inspect commission summary and a filterable ledger |
| Create an in-process bot pool with an optional shared treasury |
| Add a bot to a pool, optionally paying as it through the treasury |
| Remove a bot from a pool |
| Report pool treasury and per-bot spend counters |
Param | Type | Notes |
| string | Amount in USD (e.g., |
| string | Recipient wallet address ( |
| string | URL or description of what you're paying for |
| string | Bot identifier (defaults to env) |
| string | Network CAIP-2 ID (default: Base Sepolia) |
| string | Token ticker (default |
| string | Repeat call with the same key returns the cached result |
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| number | Max events to return (default: 10) |
Param | Type | Notes |
| string | Unique bot identifier |
| number | Initial trust level 0-5 (default: 1) |
| string | Repeat register with the same key returns the cached result |
Read-only discovery. Requires no API key and makes zero network calls. Surfaces only the public open-core registry — operator-private mainnet addresses are never shown (e.g. EURC advertises its Base Sepolia testnet deployment only).
No parameters.
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
Returns status, version, uptime, timestamp, plus any extra fields the
facilitator reports.
Tightens an agent's own limits. The facilitator enforces the operator ceiling and may reject attempts to loosen beyond policy.
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| number | Max USD per transaction |
| number | Max USD spend per day |
| number | Max transactions per hour |
| string[] | Allowlist of recipient addresses |
Param | Type | Notes |
| string | Bot identifier (defaults to env) |
| enum | Filter ledger by |
| string | Ledger start date (ISO 8601) |
| string | Ledger end date (ISO 8601) |
| number | Max ledger entries (default: 50) |
| number | Ledger pagination offset |
Creates an in-process bot pool for this MCP session. Treasury accounting is in-memory; the facilitator remains the authoritative limit.
Param | Type | Notes |
| string | Identifier for this pool (used by allocate/revoke/status) |
| number | Optional shared daily spend cap across all bots |
Param | Type | Notes |
| string | Pool identifier |
| string | Bot identifier to add to the pool |
| number | Initial trust level 0-5 |
| object | Optional |
Param | Type | Notes |
| string | Pool identifier |
| string | Bot identifier to remove |
Param | Type | Notes |
| string | Pool identifier |
PayBot MCP can wrap any tool — not just payments — so a dangerous call must pass policy before it runs, an irreversible call pauses for a named human's approval, and every outcome leaves a tamper-evident, replayable trace in core's audit chain. This is the kill-switch + black-box-recorder for MCP tool calls.
registerGovernedTool(server, def, client, opts) is a higher-order registrar.
Each wrapped call:
builds an ActionIntent — verb = tool name, target_ref = a
registrar-provided extractor over the args (opaque, never raw PII),
params_hash = SHA-256 of the canonical (key-sorted) JSON of the args,
actor.subject_ref = the configured bot id, channel: 'mcp';
calls core POST /actions/govern;
acts on the verdict:
allow → runs the tool, and appends executed: params_hash=…, result_hash=… to the output so the trace binds intent → execution;
deny → does not run; returns the gate reasons;
pending → (default block mode) polls GET /approvals/:id with backoff
until approved/denied/expired or approvalTimeoutMs (default 120 s); on
approval it re-verifies params_hash AND requires the approval to be
action-shaped before executing (TOCTOU + cross-route defence), then runs
once. (return mode hands back the approval_id instead.)
Approve via the ACTION route — enforced, not just advised. A paused action is approved/denied through
POST /actions/approvals/:id/approve(or.../deny) — not the payment/approvals/:id/approveroute, whose grant path attempts settlement. The approval row is the shared A5a store, so a payment-route approve still flips it toAPPROVED; the interceptor therefore does not trust a baredecision === 'APPROVED'. The payment approve route always runs settlement and writes astate(SETTLE_FAILED/RESUME_CONTEXT_UNAVAILABLEfor an action); the action route never settles and writes nostate. The interceptor executes only when the approved row has no settlementstate— a presentstateis treated as a payment-route claim and the call fails closed withWRONG_APPROVAL_ROUTE(handler never runs). This closes the cross-route hazard where a human approving what they believe is a payment would otherwise authorize an agent's irreversible action.
Governance adds one network round-trip per governed call (/actions/govern).
A pending action in block mode holds open only as long as the stdio session
lives — MCP stdio servers are single-session, so a session that ends drops a
blocking wait. Operators drive approval from a second terminal (curl/dashboard),
exactly like the HITL payment demo.
Fail closed. If governance is unreachable (network error, timeout, 5xx,
malformed body) an irreversible or unknown action is refused
(GOVERNANCE_UNREACHABLE) — an unreachable governor never silently allows.
A reversible tool MAY set failOpen: true (demo-only convenience; ignored
for irreversible verbs).
Risk class is set by the registrar (operator code), never by the model. An agent cannot self-declare its destructive tool "reversible."
No raw args leave the process. Only the params_hash and the extractor's
target_ref are sent to core; raw arguments (connection strings, PII) stay
local.
No bypass. Governance is applied at registration. A server that registers a raw tool is ungoverned by definition — we govern what is wrapped, and make no claim to intercept everything.
Set PAYBOT_ENABLE_DEMO_TOOLS=true to register two mock governed tools:
Tool | Risk class | Effect |
| irreversible | MOCK — touches nothing; pauses for human approval, then returns a labelled mock confirmation |
| reversible | MOCK — proves the allow path; flows straight through |
A published MCP server must not advertise a delete_database tool to every
agent, so these stay off unless the flag is explicitly true.
See docs/runbooks/governed-action-demo.md
for the exact recorded-demo script (govern → pending → approve → mock execute →
replayable audit proof).
import { createMcpServer } from 'paybot-mcp/server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const server = createMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);Check spending limits, trust level, and remaining daily budget for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the full behavioral burden, and it does disclose the returned fields (limits, trust level, remaining daily budget), which is genuinely useful. However, it never states that this is a non-mutating read, whether it requires authentication, or whether the values are cached/live. Useful but incomplete for a zero-annotation tool.
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?
One front-loaded sentence listing exactly what is checked, with no filler, preamble, or restatement of the tool name. 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?
For a one-optional-parameter read tool with no output schema, disclosing the three returned values is the key missing piece and it is present. The remaining gap is the absence of any safety/profile statement (read-only, no side effects), which would matter more if annotations existed to lean on.
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 the single botId parameter is fully documented in the schema, including its env-var default. The description adds nothing about the identifier (format, whether it may be omitted), so the baseline 3 for schema-driven params 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?
The description names a specific verb (Check) and enumerates the exact resource set returned: spending limits, trust level, and remaining daily budget, scoped to 'a bot'. That is far more useful than a tautology and distinguishes it from mutation siblings like paybot_set_spending_limit, though it never explicitly names which sibling to pick instead.
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?
There is no stated when-to-use context, no prerequisites, and no mention of alternatives such as paybot_health_extended, paybot_history, or paybot_set_spending_limit. The agent must infer that this is a pre-payment status check purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect commission for transparency: aggregate summary (totals + rate) and a filterable, paginated ledger.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) | |
| limit | No | Max ledger entries (default: 50) | |
| offset | No | Ledger pagination offset | |
| status | No | Filter ledger entries by status | |
| endDate | No | Ledger end date (ISO 8601) | |
| startDate | No | Ledger start date (ISO 8601) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the return shape (aggregate totals + rate, paginated ledger) and filtering, but does not state that the operation is read-only, whether it requires auth, or whether it has side effects.
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?
A single front-loaded sentence with no filler; it states the tool's purpose and output structure immediately. Every phrase contributes to understanding what the tool returns.
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 no output schema, the description helpfully names the two return components (summary and ledger) and notes filtering/pagination. It is reasonably complete for a read-oriented inspection tool, though it omits usage context and safety guarantees that annotations would normally cover.
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%, so the schema already documents all six parameters, including defaults, enums, and date formats. The description only groups the ledger as 'filterable, paginated' and adds no parameter syntax or constraints beyond the schema, matching the 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?
States a specific verb and resource ('Inspect commission') and describes the two outputs (aggregate summary and filterable ledger). It does not, however, differentiate itself from siblings like paybot_history or paybot_balance, so an agent must infer that this is commission-specific.
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?
No explicit when-to-use, when-not-to-use, or alternative tool guidance. 'For transparency' implies a reporting purpose but does not tell an agent when to choose this over paybot_history or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check extended facilitator health: status, version, uptime, timestamp, plus any extra fields the facilitator reports (e.g. relayer/gas/AML status).
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose that the response includes variable, facilitator-reported extra fields (relayer/gas/AML), which is genuinely useful and hints at an open-ended return shape. However, it says nothing about auth requirements, rate limits, or whether the call is side-effect free.
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?
One compact sentence with the action front-loaded and the returned fields listed in decreasing order of importance. No filler, though the field enumeration makes it read slightly like a spec line rather than prose.
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?
Given no output schema, the description usefully compensates by naming the returned fields, and the single parameter is fully documented in the schema. It remains incomplete on the usage dimension (when to call it, what a failure looks like) for a diagnostic tool an agent would rely on to gate other operations.
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% for the single optional botId parameter, and the schema already documents the env-var default. The description adds no parameter-level meaning, so the 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?
Specific verb (check) plus resource (facilitator health) and an explicit enumeration of what the tool surfaces: status, version, uptime, timestamp, and facilitator-reported extra fields. The 'extended' qualifier signals a richer variant of a plain health check. It stops short of naming any sibling tool, so an agent must infer its role relative to the paybot_* family.
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?
No when-to-use guidance, no prerequisites, and no mention of an alternative (e.g. a non-extended health check that 'extended' implies). The agent is left to infer that this is a diagnostic call to run before or alongside other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View recent payment history and audit events for a bot.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) | |
| limit | No | Max events to return (default: 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It implies a read-only operation via 'View' but does not disclose pagination behavior, default retention period, ordering, authentication needs, or return format. This leaves a significant gap for a tool with zero annotation coverage.
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 a single, front-loaded sentence with zero wasted words. It is appropriately sized for a simple read tool and gets to the point immediately.
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?
Given the low complexity (2 optional parameters) and full schema coverage, the description is minimally adequate but missing usage context and any detail about return values since no output schema exists. It states the purpose but leaves the agent without guidance on when and how to use the tool effectively.
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%, so the schema already documents both parameters fully, including defaults for botId and limit. The description adds no additional meaning beyond what the schema provides, making the baseline of 3 appropriate.
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 clearly states a specific verb (View) and resource (recent payment history and audit events for a bot), making the tool's function immediately understandable. It does not explicitly differentiate from siblings like paybot_balance or paybot_commission_inspect, so it falls short of a 5.
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?
There is no explicit guidance on when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. Usage is only implied by the resource name, which is insufficient for confident tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the networks and tokens PayBot supports. Read-only, offline, requires no API key. Surfaces only the PUBLIC open-core registry — operator-private mainnet addresses are never shown.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses read-only/offline operation, no API-key requirement, and a meaningful data-visibility constraint ('only the PUBLIC open-core registry — operator-private mainnet addresses are never shown'). It does not describe the shape of the returned data, which is the main remaining gap.
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 short sentences, front-loaded with the purpose, then operational characteristics, then the scoping caveat. Each sentence adds distinct value with no filler.
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, zero-parameter discovery tool this is nearly complete: purpose, safety/auth profile, and visibility limits are all covered. The one omission is any hint about the return shape (no output schema exists), which an agent might want before consuming the result.
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 tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly does not waste space describing nonexistent inputs.
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 ('List') and resource ('the networks and tokens PayBot supports') with a clear scope. None of the sibling tools (balance, pay, history, pool_*, etc.) overlap with this discovery function, so an agent can distinguish it immediately.
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 purpose implies the usage context (discovering supported networks/tokens), and 'read-only, offline, requires no API key' tells the agent this is cheap and safe to call freely. However, it never explicitly says when to reach for this versus siblings like paybot_pay or paybot_balance, nor does it name an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a payment (USDC by default) for an API, service, or resource. Returns transaction hash and commission breakdown. Supports alternate tokens and idempotency.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) | |
| token | No | Token ticker to pay with (default: USDC). e.g. USDC, EURC, DAI | |
| amount | Yes | Amount in USD (e.g., "0.05" for 5 cents) | |
| network | No | Network CAIP-2 ID (default: eip155:84532 Base Sepolia) | |
| resource | Yes | URL or description of what you are paying for | |
| recipient | Yes | Recipient wallet address (0x...) | |
| idempotencyKey | No | Optional idempotency key; a repeat call with the same key returns the cached result |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It does disclose useful traits: default token, idempotency caching semantics, and that the response includes a transaction hash and commission breakdown. However, for a financial mutation it omits irreversibility, permission/auth requirements, and any spending-limit interaction.
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 short sentences, front-loaded with the action and object, then return values, then optional features. No filler or redundancy.
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?
No output schema exists, and the description helpfully summarizes returns (tx hash, commission breakdown). But for a 7-parameter payment tool with no annotations, it leaves out important context an agent needs: irreversibility, required setup, and how it relates to paybot_set_spending_limit or pool 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?
Schema description coverage is 100%, so the schema already documents all seven parameters including defaults, network CAIP-2 format, and idempotency key. The description only echoes the USDC default and idempotency, adding no syntax or constraint detail 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 specific verb and resource: 'Make a payment ... for an API, service, or resource,' and notes default token USDC and return contents. It is clearly distinguishable from siblings like paybot_balance or paybot_history, though it doesn't name any sibling explicitly.
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 description never says when to use this versus alternatives such as paybot_set_spending_limit or paybot_pool_allocate, nor does it state prerequisites (e.g., registration or spending limits). Usage is only implied by the object of payment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a bot to a pool, and optionally make a payment as that bot through the shared treasury.
| Name | Required | Description | Default |
|---|---|---|---|
| pay | No | Optional payment to execute as this bot after allocation | |
| botId | Yes | Bot identifier to add to the pool | |
| poolId | Yes | Pool identifier | |
| trustLevel | No | Initial trust level 0-5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that the payment is executed 'as that bot through the shared treasury', which is real behavioral context, but it omits authorization requirements, interaction with spending limits (there is a sibling paybot_set_spending_limit), atomicity of allocation vs. payment, and reversibility.
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?
A single sentence that front-loads the primary action (allocation) and marks the payment as optional. No filler or redundancy.
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 tool that mutates pool membership and can move funds, the description covers the what but not the surrounding constraints (permissions, spending limits, failure behavior). No annotations or output schema exist to fill those gaps, so it is adequate but incomplete for the risk level.
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 the nested pay object documents token, amount, network, resource, and recipient in detail. The description adds only the framing that pay is optional and treasury-sourced, so the 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?
States a specific verb and resource ('Add a bot to a pool') plus an optional secondary action (payment as that bot). It is clear what the tool does, but it does not explicitly differentiate itself from siblings like paybot_pool_create or paybot_pool_revoke, leaving the agent to infer the lifecycle position.
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?
No when-to-use guidance, no prerequisites, and no mention of alternatives such as paybot_pay for standalone payments or paybot_pool_revoke for removal. The agent gets the action but not the context that selects it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an in-process bot pool with an optional shared daily treasury. The pool lives for this MCP session; treasury accounting is in-memory and the facilitator remains authoritative.
| Name | Required | Description | Default |
|---|---|---|---|
| poolId | Yes | Identifier for this pool (used by allocate/revoke/status) | |
| sharedDailyLimitUsd | No | Optional shared daily spend cap across all bots |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does disclose meaningful traits: the pool is in-process and session-scoped, treasury accounting is in-memory, and the facilitator stays authoritative. It does not say what happens on a duplicate poolId, whether creation is idempotent, or what auth is required for a mutating call.
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 sentences, no filler, and the primary action is front-loaded before the lifecycle caveats. Every clause carries information.
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 two-param mutating tool with no annotations and no output schema, the description covers lifecycle and authority adequately, but omits duplicate-id behavior, error modes, and interaction with paybot_pool_allocate/revoke that an agent would need to use it correctly.
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%, so both parameters are already documented, including that poolId is reused by allocate/revoke/status. The phrase 'optional shared daily treasury' loosely maps to sharedDailyLimitUsd but adds no syntax or enforcement detail 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 specific verb and resource ('Create an in-process bot pool'), plus an optional capability (shared daily treasury). The 'pool' resource clearly separates it from sibling families like paybot_pay or paybot_balance, though no sibling is named explicitly.
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?
No guidance on when to create a pool versus using individual bot spending limits (paybot_set_spending_limit), nor prerequisites such as registration first. The session-lifetime note is context, not usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a bot from a pool.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | Yes | Bot identifier to remove | |
| poolId | Yes | Pool identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it says nothing about permissions required, whether the removal is reversible, or what happens to the bot's existing pool allocation. For a mutation tool with zero structured safety hints, this is a meaningful gap.
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?
A single front-loaded sentence with no filler, which is appropriate for a two-parameter mutation. It is efficient, though its brevity edges into under-specification rather than true conciseness.
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 no annotations, no output schema, and no mention of side effects, permission requirements, or post-removal state, an agent lacks enough to invoke this confidently. A mutation tool needs at least that much context.
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 both poolId and botId documented inline, so the schema already does the work. The description adds no format, constraint, or relationship detail beyond restating the two parameters in prose.
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?
Specific verb ("Remove") plus resource ("a bot from a pool"), so the action is unambiguous. It does not distinguish itself from pool siblings like paybot_pool_allocate or paybot_pool_status, which is the only thing keeping it out of 5 territory.
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?
No statement of when to use this versus paybot_pool_allocate, paybot_pool_status, or paybot_pool_create, and no prerequisites or exclusions. The agent must infer the entire decision context from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a pool's remaining shared treasury and per-bot local spend/transaction counters (in-process projection; facilitator is authoritative).
| Name | Required | Description | Default |
|---|---|---|---|
| poolId | Yes | Pool identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose a meaningful trait — the numbers are an in-process projection and the facilitator is authoritative, so values may be approximate — but it omits permission/auth requirements and any indication of failure modes for an unknown poolId.
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?
One tightly written sentence with the resource front-loaded and the authority caveat correctly subordinated in parentheses. Every clause earns its place with no filler.
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 single-parameter read tool with no output schema, the description does state what is returned (treasury balance and per-bot counters) and flags the projection caveat. It stops short of covering auth requirements or behavior on an invalid poolId, leaving a small gap.
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 a single parameter (poolId, "Pool identifier"), so the schema already documents the input. The description adds no syntax, format, or constraint detail for poolId beyond what the schema provides; 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?
The description gives a specific verb ("Report") and a precise resource: a pool's remaining shared treasury plus per-bot local spend/transaction counters. This clearly separates it from write-oriented siblings like paybot_pool_create, paybot_pool_allocate, and paybot_pool_revoke, though it never names an alternative explicitly.
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?
There is no statement of when to call this versus paybot_balance, paybot_history, or the other pool tools. The parenthetical about in-process projection vs. the facilitator implies a data-freshness caveat but does not tell the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a new bot with the PayBot facilitator. Returns the assigned trust level. Supports an optional idempotency key for safe re-issue.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | Yes | Unique bot identifier | |
| trustLevel | No | Initial trust level 0-5 (default: 1) | |
| idempotencyKey | No | Optional idempotency key; a repeat register with the same key returns the cached result |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return value (trust level) and the idempotency contract, which is genuinely useful, but says nothing about authorization requirements, side effects of registration, or what happens on a duplicate botId without a key.
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 short sentences, no filler, and the core action plus its return value are front-loaded ahead of the optional idempotency note. Every sentence 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?
For a three-parameter mutation with no output schema and no annotations, the description covers the action, the returned value, and the idempotency escape hatch, which is most of what an agent needs. It stops short of failure modes (duplicate botId, permission requirements), leaving a small gap.
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%, so the schema already documents botId, trustLevel, and idempotencyKey including defaults and bounds. The description's only parameter-related content (the optional idempotency key) restates the schema field, adding no syntax or format detail. 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?
The description names a specific verb and resource ('Register a new bot with the PayBot facilitator') and states the primary output ('Returns the assigned trust level'). No sibling tool in the list performs registration, so the operation is unambiguously distinct from paybot_pay, paybot_balance, and the pool tools.
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 rather than stated: the mention of an idempotency key for 'safe re-issue' hints at the retry scenario, but the description never says when to register versus re-register, nor what to do if the bot already exists. No alternative tool is named or excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set spending limits for a bot. Tightens the agent's own limits; the facilitator enforces the operator ceiling and may reject attempts to loosen beyond policy.
| Name | Required | Description | Default |
|---|---|---|---|
| botId | No | Bot identifier (defaults to env PAYBOT_BOT_ID) | |
| maxDailySpendUsd | No | Max USD spend per day | |
| allowedRecipients | No | Allowlist of recipient addresses | |
| maxTransactionUsd | No | Max USD per transaction | |
| maxTransactionsPerHour | No | Max transactions per hour |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and usefully discloses policy behavior: self-tightening only, facilitator-enforced operator ceiling, possible rejection. It still omits what happens on success, whether it requires auth, and the response shape, so coverage is partial.
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 the action front-loaded and the enforcement caveat second. Every clause earns its place with no redundancy.
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?
No annotations and no output schema, but the description covers the critical policy semantics and the schema fully documents all parameters. An agent can call it correctly; only success behavior and auth requirements remain unspecified.
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%, so all five parameters (botId default, daily spend, recipients, per-tx max, tx/hour) are documented in the schema. The description adds no field-level meaning beyond that, so the 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?
States a specific verb+resource: 'Set spending limits for a bot.' It is clearly distinguishable from all siblings (none of which set limits), though it does not explicitly name a contrasting tool. Clear and specific but without sibling routing.
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 the key operating condition: it 'Tightens the agent's own limits,' and that loosening beyond policy 'may reject' attempts. This tells the agent the direction of allowed change and a rejection condition, but names no alternative tool or explicit when-not scenario.
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.3.4paybot_balancepaybot_commission_inspectpaybot_health_extendedpaybot_historypaybot_list_networks_and_tokenspaybot_paypaybot_pool_allocatepaybot_pool_createpaybot_pool_revokepaybot_pool_statuspaybot_registerpaybot_set_spending_limitScored across 12 tools
Most tools target distinct resources: bot-level operations (balance, pay, history, register, set_spending_limit) are clearly separated from pool operations (pool_create, pool_allocate, pool_status, pool_revoke). Minor potential overlap between paybot_history and paybot_commission_inspect (both surface ledger-like data), and paybot_pool_allocate includes an optional payment that touches paybot_pay's domain, but descriptions make boundaries clear enough.
All tools share the paybot_ prefix and use snake_case throughout. There is a mild inconsistency in ordering: some are verb_noun (list_networks_and_tokens, set_spending_limit, pool_create), while others are bare nouns (balance, pay, history, register, health_extended), but the convention remains predictable and readable.
12 tools is well-scoped for a payment bot server covering registration, payments, limits, history, commissions, health, and pool management. Each tool appears to earn its place with no obvious redundancy or padding.
Core lifecycle is covered: register, pay, check balance, view history, set limits, inspect commissions, and manage pools. Gaps include no bot deregistration/unregister (pool_revoke only removes from a pool) and no dedicated bot detail/profile lookup beyond balance, but these are minor and workable.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Marketplace and payment rail for AI agents: list, buy and settle with signed receipts.
Paid MCP tools behind one endpoint. Agents pay per call in USDC on Base via x402.
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.