Paywall ANY stdio MCP server with Lightning, without modifying it. paywall-mcp is a generic sidecar: configure it with an upstream MCP server command and a per-tool price map, and it transparently:
Forwards tools/list from the upstream to the LLM client, with prices appended to each tool's description.
Intercepts tools/call: free tools pass through; priced tools require a paid Lightning invoice (via Nostr Wallet Connect / NIP-47) before the call is forwarded.
No code changes to the upstream server. Works with Anthropic's reference MCP servers, your own, or any third-party MCP server that speaks stdio.
v0.1 — proxy + payment gate complete. Spawns a stdio upstream as a child process; per-tool pricing via env; in-memory invoice cache + replay protection; audit log; read-only mode. Persistent cache + HTTP/SSE upstream transport deferred to v0.2.
Modern paid-API patterns (Lightning paywall, L402, micropayments) exist for HTTP but the MCP ecosystem has no standard for paid tool calls. Building it into each individual server is repetitive and error-prone. paywall-mcp is the missing sidecar: write your tools as a normal MCP server, then wrap it with paywall-mcp to charge sats per call.
Related MCP server: protect-mcp
For any priced tool:
First call — LLM calls priced_tool({...args}) without payment_hash. paywall-mcp issues a bolt11 invoice through your NWC wallet and returns:
{
"error": "payment_required",
"invoice": "lnbc...",
"payment_hash": "abc123...",
"amount_sats": 21,
"expires_in_seconds": 600,
"next_step": "Pay this bolt11 ..."
}Payment — the LLM (or its operator) pays the invoice. Easiest path: use nwc-mcp — the same LLM can call nwc_pay_invoice to settle.
Second call — LLM calls priced_tool({...args, payment_hash: "abc123..."}). paywall-mcp verifies settlement via NWC lookup_invoice, strips payment_hash from the args, forwards the original call to the upstream, returns the upstream's result.
Replay protection: the same payment_hash cannot be redeemed twice. Buyers pay a fresh invoice for each call.
Charge sats for premium tools in an MCP server you already have, by adding one wrapper process.
Per-tool pricing tiers — free_lookup: 0, premium_analysis: 100, rare_alpha_signal: 5000. Buyers see prices in tool descriptions.
Bundle-and-resell third-party MCP servers — wrap someone else's open-source MCP server with your paywall and offer it as a managed paid service.
A/B test pricing — adjust PAYWALL_PRICE_MAP in env, restart, you're at the new price.
Time-limited promotional pricing — start at 21 sats, raise to 100 sats once usage proves the value.
Node 20+
An existing stdio MCP server to wrap (paywall-mcp doesn't host tools itself; it gates an upstream's tools).
A NIP-47 NWC connection string for the seller's receive wallet. make_invoice + lookup_invoice are the only permissions paywall-mcp needs. A receive-only NWC connection is perfectly fine and recommended — paywall-mcp never spends.
# From npm
npx -y paywall-mcp
# From source
git clone <repo>
cd paywall-mcp
corepack enable pnpm
pnpm install
pnpm buildcp .env.example .env
# edit .env: set PAYWALL_UPSTREAM_COMMAND/ARGS, NWC_CONNECTION_STRING, pricesThe server auto-loads .env from its own directory (next to dist/) — deliberately NOT from cwd, to avoid env collisions when running multiple MCP servers in the same Claude Code session.
Var | Purpose |
| Executable to spawn as the upstream MCP server (e.g., |
| JSON array of args passed to the upstream command (e.g., |
Var | Purpose |
| NIP-47 NWC URI for the seller's RECEIVE wallet. |
Var | Default | Purpose |
|
| Default price for any tool not in the price map. |
|
| JSON object mapping tool names to sat prices. Per-tool 0 = free; missing = use default. Example: |
Var | Default | Purpose |
| (parent cwd) | Working directory for the upstream child process. |
| (inherits) | JSON object of env-var overrides for the upstream. |
|
| Disables all paid tool calls ( |
|
| Invoice TTL. Past this, |
|
| Label appended to each priced tool's description in |
|
| Server log. |
|
| NDJSON audit log (one line per call). |
paywall-mcp-test serverThe companion paywall-mcp-test package exposes a single tool — premium_compliment. It already implements its own paywall pattern internally, but it's also a convenient stand-in for "any upstream MCP server" to demonstrate paywall-mcp itself.
.env:
PAYWALL_UPSTREAM_COMMAND=node
PAYWALL_UPSTREAM_ARGS=["/abs/path/to/paywall-mcp-test/dist/index.js"]
NWC_CONNECTION_STRING=nostr+walletconnect://...
PAYWALL_DEFAULT_PRICE_SATS=21
PAYWALL_PRICE_MAP={"premium_compliment":21}Wire paywall-mcp (not the upstream directly) into your MCP client:
{
"mcpServers": {
"paywall": {
"command": "npx",
"args": ["-y", "paywall-mcp"],
"env": {}
}
}
}Now from your agent:
1. tools/list → premium_compliment ... (💰 21 sats) This tool requires ...
2. premium_compliment({}) → returns invoice + payment_hash
3. nwc_pay_invoice(invoice) → buyer pays
4. premium_compliment({ payment_hash: "..." }) → upstream's result returnedtools/list → upstream.listTools() → augment descriptions with prices → return
tools/call:
if price == 0 → upstream.callTool(args) (passthrough)
elif PAYWALL_READ_ONLY → refuse with paywall_read_only (block)
elif no payment_hash → gate.issue() → return bolt11 + hash (issue)
elif bad hash format → refuse with invalid_payment_hash (block)
else (have hash):
gate.verify() ──┬─ unknown_payment_hash → block
├─ payment_hash_already_redeemed → block (replay)
├─ payment_hash_tool_mismatch → block
├─ payment_not_settled → block
└─ ok → strip hash → upstream.callTool() (paid passthrough)Audit log entries (NDJSON, one per request):
outcome: "ok" — invoice issued, free passthrough, or paid passthrough completed
outcome: "blocked" — read-only refusal, invalid hash, replay, mismatch, not-settled
outcome: "error" — upstream call failed, NWC lookup_invoice failed, etc.
Tail the audit log for ground truth — independent of whatever the LLM tells you.
tail -f paywall-mcp-audit.log | jq .{
"mcpServers": {
"paywall": {
"command": "npx",
"args": ["-y", "paywall-mcp"],
"env": {}
}
}
}Same .env-via-binary-dir pattern as the rest of the substrate — leave env empty in the client config; secrets stay in paywall-mcp/.env.
pnpm typecheck
pnpm test # 13 vitest cases (config resolution + payment-gate state machine)
pnpm build # ~18 KB ESM bundlenwc-mcp — Lightning wallet for the buyer. Lets the agent pay the invoices paywall-mcp issues. The matching half of the agent-pays-a-paid-tool loop.
nostr-ops-mcp — NOSTR identity, publishing, encrypted DMs.
marketplace-mcp — Run a NIP-15 / Shopstr storefront from an agent.
albyhub-admin-mcp — Alby Hub node-admin via HTTP API.
MIT — see LICENSE.
Built by LLMOps.Pro.
NOSTR: npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — follow, DM, zap.
Lightning Address: sovereigncitizens@getalby.com — for support zaps and "this was useful" tips.
Bug reports / feature requests: open a GitHub issue (link forthcoming).
Security issues: please disclose privately via NOSTR DM before opening a public issue.
Echoes back the input string
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Message to echo |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the annotations (readOnlyHint, idempotentHint, destructiveHint) and essentially restates the implied behavior. It adds no extra contextual detail such as side effects, rate limits, or edge cases, but for such a trivial operation the annotations and description together provide sufficient transparency.
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 that fully conveys the function without any wasted words. It is appropriately concise for the tool's simplicity.
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 tool's extremely low complexity, a single parameter with full schema coverage, and annotations that define the safety profile, the description is complete. No output schema is needed since 'echoes back' clearly indicates the return value is the input string.
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 input schema already provides a description for the 'message' parameter ('Message to echo'), and the tool description does not add additional meaning beyond that. With 100% schema coverage, the baseline of 3 applies; the description and schema together are adequate but not enriched.
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 uses a specific verb ('echoes back') and identifies the resource (input string), making the tool's purpose immediately clear. It is also distinguishable from sibling tools that retrieve or manipulate resources, as echo uniquely returns the provided input unchanged.
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. The description only states what it does, not in which contexts it is appropriate or when other tools should be preferred, leaving the agent to infer usage from the tool's name and simplicity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Demonstrates how annotations can be used to provide metadata about content.
| Name | Required | Description | Default |
|---|---|---|---|
| messageType | Yes | Type of message to demonstrate different annotation patterns | |
| includeImage | No | Whether to include an example image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, which covers the safety profile. However, the description adds no behavioral context beyond this, such as what an 'annotated message' looks like or what the tool returns. The vague statement about demonstrating annotations does not provide useful behavioral information.
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 sentence, which is concise, but it is under-specified and does not earn its place. It provides almost no useful information, making it more of a placeholder than a helpful description.
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 and only a vague description, the agent is left without a clear understanding of the tool's purpose, inputs, or return value. The complexity is low, but the description is too incomplete to support correct invocation or expectation setting.
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%, with both parameters ('messageType' and 'includeImage') having descriptions. The tool description itself provides no parameter details, but since the schema fully covers parameter semantics, the baseline of 3 is 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 states 'Demonstrates how annotations can be used to provide metadata about content,' which is vague and does not clearly indicate what the tool actually does (e.g., returns a message with annotations). It is not a tautology, but it lacks a specific verb and resource, and it does not distinguish the tool from its siblings like 'get-resource-links' or 'get-structured-content'.
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 guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions, leaving the agent without any basis for selecting it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns all environment variables, helpful for debugging MCP server configuration
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the core safety profile. The description adds the debugging context but does not disclose potential sensitivity of environment variables (e.g., containing secrets), which is a behavioral aspect beyond annotations. However, the bar is lower given the strong 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 that states exactly what the tool does and why it's useful. Every word earns its place, with no redundancy or 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 tool with strong annotations, the description is sufficiently complete. It states the output scope ('all environment variables') and a practical use case. It could mention the output format (e.g., key-value pairs), but that is not necessary given the tool's simplicity and lack of an output schema.
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?
Since there are zero parameters, the schema is trivially complete (100% coverage). According to the baseline rule for 0 params, a score of 4 is appropriate; the description does not need to elaborate on parameter details.
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 states 'Returns all environment variables' with a specific verb and resource, clearly distinguishing it from siblings like get-sum or get-resource-links. The added context about debugging MCP server configuration reinforces its purpose.
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 specifies a clear use case: 'helpful for debugging MCP server configuration.' It provides context for when to use the tool, though it doesn't explicitly mention alternatives or when not to use it, which is acceptable given the simplicity of the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns up to ten resource links that reference different types of resources
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of resource links to return (1-10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds 'up to ten' and 'different types of resources', giving some behavioral context but not deep detail on output format, ordering, or edge cases.
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 sentence, front-loaded with the core behavior, and every word is purposeful. It avoids verbosity and repetition of schema details.
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 simple signature (one parameter, no output schema), the description adequately conveys the return type (list of resource links) and the limit. However, it does not describe the structure of individual links, which could be a minor gap for an agent needing to parse the results.
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 only parameter, count, has a description in the schema covering range and default. The tool description adds no additional meaning beyond confirming the upper limit, so it relies on the schema's parameter documentation.
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 the action (Returns), the object (resource links), and the scope (up to ten, different types). It differentiates from siblings like get-resource-reference by emphasizing a collection of varied links.
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 guidance is provided on when to use this tool versus alternatives such as get-resource-reference. The phrase 'different types' implies a general-purpose use, but there are no stated conditions, exclusions, or pointers to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a resource reference that can be used by MCP clients
| Name | Required | Description | Default |
|---|---|---|---|
| resourceId | No | ID of the text resource to fetch | |
| resourceType | No | Text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds no further context. It doesn't describe the nature of the reference (e.g., URI, ID), any side effects, or prerequisites, so it adds no value beyond the structured annotations.
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 concise sentence with no padding. While it is short, it lacks useful detail, but the conciseness itself is appropriate for the tool's apparent simplicity. The sentence is front-loaded with the action and result.
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 and only a vague description, the tool's overall behavior and return value are underspecified. It doesn't explain what a resource reference is, how it relates to resourceType, or how it differs from siblings. The description is too thin to be complete for a tool with two parameters and no output schema.
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 description does not reference parameters at all. Schema coverage is only 50% (resourceId has a description, resourceType does not). The description should have compensated for the missing resourceType semantics but fails to do so, leaving the agent without essential parameter understanding.
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 the tool returns a resource reference, using a specific verb and object. However, it doesn't distinguish itself from sibling tools like get-resource-links, leaving ambiguity about what makes a 'reference' different.
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 provides no guidance on when to use this tool vs alternatives. It doesn't mention the parameters or any conditions under which this tool would be preferred, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns structured content along with an output schema for client data validation
| Name | Required | Description | Default |
|---|---|---|---|
| location | Yes | Choose city |
| Name | Required | Description |
|---|---|---|
| humidity | Yes | Humidity percentage |
| conditions | Yes | Weather conditions description |
| temperature | Yes | Temperature in celsius |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive, so the description's burden is lighter. It adds the behavioral detail that the output includes an output schema for client-side validation, which is useful, but it does not explain how the location parameter affects the returned content or any other runtime 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?
The description is a single, front-loaded sentence that clearly states the core function. It contains no filler or redundant content, and every word contributes to the purpose.
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?
The tool is simple with one fully documented parameter, good annotations, and an output schema, so the description does not need to explain return formats. However, it lacks explicit context about how the location parameter determines the returned content, which is a notable gap given the description's brevity.
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 input schema covers 100% of the parameter semantics with the 'location' description and enum values. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is 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 states that the tool returns structured content and an output schema for validation, which identifies the main action and resource. However, it does not explicitly distinguish this tool from siblings like get-resource-links or get-env, and 'structured content' is somewhat generic.
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 provides no guidance on when to use this tool versus alternatives. It does not mention suitable contexts, prerequisites, or exclusions. The only hint is the name and schema, but the description itself offers no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the sum of two numbers
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | First number | |
| b | Yes | Second number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no additional behavioral context beyond the annotations, such as error handling or edge cases, but for a pure numeric sum, there is little else to disclose. No contradiction with annotations.
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 that conveys the entire purpose with zero wasted words. It is appropriately sized for the tool's trivial complexity.
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, full schema coverage, and informative annotations, the description is complete for an agent to select and invoke the tool. It states the return behavior ('Returns the sum'), and no output schema is necessary because the result type is implicitly a number.
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 input schema already describes both parameters ('a' as 'First number' and 'b' as 'Second number') with 100% coverage. The description only refers to 'two numbers' without adding new meaning about formats, constraints, or relationships. Baseline 3 is appropriate since the schema carries the parameter documentation.
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 states a specific verb ('Returns') and resource ('the sum of two numbers'), clearly indicating the tool's arithmetic function. It distinguishes itself from sibling get-* tools by being the only one that computes a numeric sum, so there is no ambiguity.
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 does not explicitly state when to use this tool or mention alternatives. However, the purpose is so self-evident that the usage context is implied: use it whenever the sum of two numbers is needed. No exclusions or alternative tools are provided, which is acceptable given the tool's simplicity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a tiny MCP logo image.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the resource type (image) but does not disclose additional behavioral details such as output format or if any network call occurs.
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, focused sentence with no wasted words, making it optimally concise and easy to parse.
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 trivial zero-parameter tool with no output schema, the description fully communicates its purpose. There are no missing prerequisites, side effects, or complex behaviors to document.
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 zero parameters and 100% schema coverage, there is no parameter information needed. The description appropriately focuses on the output rather than parameter details, and the baseline of 4 is warranted.
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 uses a specific verb ('Returns') and identifies the exact resource ('tiny MCP logo image'), making the tool's purpose immediately clear. It is distinct from sibling tools, which serve different functions.
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 implies the tool should be used when a tiny MCP logo image is needed, but it provides no explicit context or exclusions. Sibling tools are not mentioned, and there is no guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compresses a single file using gzip compression. Depending upon the selected output type, returns either the compressed data as a gzipped resource or a resource link, allowing it to be downloaded in a subsequent request during the current session.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | URL or data URI of the file content to compress | https://raw.githubusercontent.com/modelcontextprotocol/servers/refs/heads/main/README.md |
| name | No | Name of the output file | README.md.gz |
| outputType | No | How the resulting gzipped file should be returned. 'resourceLink' returns a link to a resource that can be read later, 'resource' returns a full resource object. | resourceLink |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotent=true, and destructive=false. The description adds value by explaining the output-type-dependent behavior and the session-limited download aspect, which is not captured by annotations. No contradictions exist.
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, concise and front-loaded with the primary action. Every clause contributes meaning: compression, output type, and session-limited download. There is no redundant or filler text.
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 tool's moderate complexity, the description covers the essential aspects: what it does, how the output varies, and the session constraint. Without an output schema, it clearly explains the return value. It could mention edge cases like file size limits or URL formats, but overall it is sufficiently complete for an agent 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 the baseline is 3. The description mentions 'Depending upon the selected output type' which alludes to the outputType parameter, but adds no additional meaning beyond the schema's per-parameter descriptions. It does not compensate with extra detail because the schema already fully documents all three parameters.
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?
Description clearly states the verb 'Compresses' and the resource 'a single file', and specifies the output as gzipped resource or link. This distinguishes it from sibling tools like echo or get-sum, which have different purposes. The mention of 'resource link' and 'session' also helps differentiate it from other resource-related 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?
The description conveys when to use the tool: when you need to compress a file and either get the compressed data directly or a link for later download in the current session. It gives clear context but does not explicitly name alternatives or state when not to use it. This is a clear context without exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulates a deep research operation that gathers, analyzes, and synthesizes information. Demonstrates MCP task-based operations with progress through multiple stages. If 'ambiguous' is true and client supports elicitation, sends an elicitation request for clarification.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The research topic to investigate | |
| ambiguous | No | Simulate an ambiguous query that requires clarification (triggers input_required status) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since annotations are all false and provide no safety profile, the description carries the behavioral disclosure burden. It discloses that the tool simulates rather than performs real research, mentions multi-stage progress, and specifies the conditional elicitation behavior contingent on the 'ambiguous' flag and client support. No contradiction with annotations.
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 concise sentences: the first front-loads the core purpose, the second adds a conditional detail. No redundant 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?
The tool is a simulation with no output schema and no meaningful annotations. The description covers the key aspects: simulation purpose, multi-stage progress, and ambiguity handling. It could provide slightly more detail on what the progress stages look like or what the final output represents, but it is sufficient for a demonstration 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% for both parameters, so baseline is 3. The description adds value by explaining how 'ambiguous' triggers an elicitation request when the client supports it, which goes beyond the schema's note about triggering input_required status. It also links the parameter to the simulation flow.
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 uses the specific verb 'simulates' to identify the action, names the resource as 'a deep research operation,' and clarifies it demonstrates MCP task-based operations, distinguishing it from sibling getter tools like echo and get-env.
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 explicitly states the tool demonstrates MCP task-based operations with progress through stages, giving clear context for when to use it (for demonstration). It does not explicitly exclude alternative uses or name sibling alternatives, but the simulation nature implies it is for testing/demo, not actual research.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggles simulated, random-leveled logging on or off.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All annotations are false, offering no hints about safety or side effects. The description mentions 'toggle' implying a state change, but it does not disclose whether the change is global, persistent, or affects other parts of the system. No behavioral details beyond the basic action are provided.
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, concise sentence that immediately communicates the tool's function. Every word is purposeful, and there is no redundant or extraneous 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 simple, parameterless toggle tool, the description is adequate to convey the core functionality. Given the absence of annotations and output schema, it could have included more context about side effects or scope, but the description still meets the needs for this low-complexity 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?
The tool has no parameters, and the schema is empty, so the description does not need to explain parameter meanings. The phrase 'on or off' implies the toggle state, which adds a slight semantic nuance. With 0 parameters, a baseline score of 4 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 clearly states the tool toggles simulated logging on or off, using a specific verb ('toggles') and a distinct resource ('simulated, random-leveled logging'). This distinguishes it from sibling tools like toggle-subscriber-updates, which handles a different resource.
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 provides no guidance on when to use this tool versus alternatives, nor any context or prerequisites. It only states the action without indicating scenarios where toggling simulated logging is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggles simulated resource subscription updates on or off.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, which aligns with a state-changing toggle. The description adds that the updates are 'simulated,' but does not disclose return behavior or side effects beyond the toggle action.
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 is front-loaded and contains no unnecessary words. Every word 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 simple, parameterless toggle with no output schema, the description is complete. It names the target and the action, and no additional behavior or prerequisites are required.
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 zero parameters, the schema provides full coverage. The description adds no parameter details but none are needed, so the baseline of 4 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 uses a specific verb ('Toggles') and resource ('simulated resource subscription updates'), clearly distinguishing it from sibling tools like toggle-simulated-logging. It is unambiguous and not a tautology.
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 context is clear: this tool is for turning subscription updates on or off. No explicit alternatives or when-not scenarios are given, but the zero-parameter design makes its usage self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Demonstrates a long running operation with progress updates.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | No | Number of steps in the operation | |
| duration | No | Duration of the operation in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the safety profile is covered. The description adds the behavioral trait of progress updates, which is beyond the annotations, but does not explain how progress is reported, whether the operation blocks, or what the response contains.
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 concise sentence of 8 words that is front-loaded with the core purpose. Every word earns its place with no unnecessary filler or repetition.
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?
While the schema and annotations provide good coverage for a simple demo tool, the absence of an output schema and the minimal description leave uncertainty about the actual operation's behavior and progress mechanism. The description is adequate but not rich enough to be fully 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 100%, with both 'steps' and 'duration' well-documented in the schema. The description adds no additional parameter semantics, but the schema already carries the full burden, so the baseline score of 3 is 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 identifies the tool as demonstrating a long-running operation with progress updates, which is more specific than simply restating the name. It distinguishes itself from sibling tools by highlighting progress updates, though the verb 'demonstrates' is slightly less direct than 'triggers' or 'runs'.
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 provides no guidance on when to use this tool versus alternatives. It does not mention use cases, exclusions, or compare with any sibling tools, leaving the agent to infer context from the name alone.
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. Dates show when Glama detected each change.
v0.1.0echoget-annotated-messageget-envget-resource-linksget-resource-referenceget-structured-contentget-sumget-tiny-imagegzip-file-as-resourcesimulate-research-querytoggle-simulated-loggingtoggle-subscriber-updatestrigger-long-running-operationMost tools have clearly distinct purposes: echo, get-env, get-sum, resource links, gzip, logging toggles, long-running operation, and research query are all distinguishable. However, trigger-long-running-operation and simulate-research-query both demonstrate long-running tasks, and get-resource-links vs get-resource-reference are similar, but descriptions clarify differences.
Tool names consistently use lowercase with hyphens (e.g., get-env, toggle-simulated-logging, trigger-long-running-operation). While verbs vary (get, toggle, trigger, simulate, gzip), the convention is uniform. 'echo' is a minor exception but acceptable.
With 13 tools, the count is within a normal range, but for a server named 'paywall-mcp', none of the tools relate to paywall functionality. The tools appear to be a collection of MCP feature demonstrations, making the count inappropriate for the server's implied purpose.
The server name suggests paywall management, but the tool surface lacks any paywall-related operations (e.g., create plan, check access, manage subscriptions). As a paywall server, this is severely incomplete. As a demo server, it covers many MCP features, but that doesn't align with the name.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Billing proxy for MCP servers. Adds Stripe and x402 crypto payments without writing billing code.
L402 MCP: 5 paid BTC/Lightning tools + fiat credits, 10-25 sats/call.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/llmops-pro/paywall-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
