Skip to main content
Glama
Payloadhq

Payload Sample MCP Server

Official
by Payloadhq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Payload Sample MCP Server

A real, installable MCP server (official mcp Python SDK, stdio transport) that demonstrates the core mechanic of Payload's paid MCP Monetization Kit: per-tool-call metering with a free quota, then a machine-readable PAYMENT_REQUIRED response once the quota is exhausted.

Small software that earns its keep.

What it does

Tool

Tier

What it does

word_count

FREE, unlimited

Count words, characters, and lines of input text.

summarize

PREMIUM

Naive extractive summary of text.

extract_keywords

PREMIUM

Naive keyword extraction from text.

Related MCP server: mcp-trust-demo

The free-quota mechanic

Premium tools get a free quota (default 5 calls, env PAYLOAD_FREE_QUOTA). After that, the server answers with a machine-readable x402-style PAYMENT_REQUIRED JSON payload — it does not crash, and it collects no real payment:

{
  "status": "PAYMENT_REQUIRED",
  "tool": "summarize",
  "free_quota": 5,
  "premium_calls_used": 5,
  "upgrade_url": "https://payloadtools.gumroad.com/l/mcp-monetization-kit",
  "message": "Free quota exhausted (5/5 premium calls used). Attach payment to continue, or get the full MCP Monetization Kit to collect real per-call USDC payments with the x402 flow: ..."
}

A hard cap (default 200 total calls, env PAYLOAD_HARD_CAP) keeps this sample from being used as a free service. Metering is in-memory and resets on every restart.

Install + run

Requires Python 3.10+.

pip install payload-sample-mcp-server
payload-sample-mcp-server

Use it in Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "payload-sample": {
      "command": "payload-sample-mcp-server"
    }
  }
}

Use it in Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "payload-sample": {
      "command": "payload-sample-mcp-server"
    }
  }
}

To run from source instead:

git clone https://github.com/Payloadhq/payload-sample-mcp-server
cd payload-sample-mcp-server
pip install -e .
payload-sample-mcp-server

What's deliberately missing (the paid kits)

This sample proves the monetization mechanic works. It does not replace the paid products:

  • Real payment collection. The MCP Monetization Kit ($69) collects actual per-call USDC payments via the x402 flow, with two verifiers (HMAC dev verifier for testing, facilitator verifier for production) — non-custodial, it verifies payment then runs your tool. It ships a paid tool registry (registerTool / callTool / listTools) with per-tool pricing, free-quota logic, an append-only usage ledger, the official SDK adapter over the stdio transport, 15 automated tests, and a working example server and paying example client.

  • Security hardening. The sample is intentionally unauthenticated. The MCP Launch Readiness Audit ($79) gives you a 48-rule scanner with concrete fixes, hardened server templates (Python and TypeScript) with bearer-token auth, per-tool scopes and rate limits, a reliability stress-test harness, a deployment readiness verifier, CI wiring, a regression suite, and a branded audit PDF report.

  • Paid APIs over x402. The x402 Paid API Starter Kit ($79) charges AI agents per API call in USDC: paid-route middleware, /.well-known/x402 manifest generator, HMAC + facilitator verifiers, append-only usage ledger, working example server, 9 automated tests. Non-custodial by design.

Payload ecosystem

Support: kylers.partners@gmail.com · "Small software that earns its keep."

License

MIT — see LICENSE.

Payload — small, sharp tools for developers. Developer portal: https://payloadhq.github.io/ · All products: https://payloadtools.gumroad.com/ · Contact: kylers.partners@gmail.com

Available Tools

3 tools
extract_keywordsB

Return the most frequent significant words in text. PREMIUM: consumes 1 free-quota call.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to analyze
limitNoMax keywords (default 10)

TDQS

B3.3/5.0
Behavior3/5

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 does disclose a genuine behavioral trait beyond the schema — the premium quota cost of one free-quota call — but says nothing about ordering, stopword handling, tie-breaking, or the shape of the returned data for a no-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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, purpose first and the cost warning second. Every sentence carries load and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must carry everything. It covers the core action and cost, but omits the return format (ranked list? tuples with counts?) and how 'significant' is defined, which an agent would need to consume results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both the required text and the optional limit (with its default of 10) are already documented in the schema. The description adds no additional semantics such as what counts as a 'significant' word, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: returning the most frequent significant words in a text. That distinguishes it meaningfully from word_count (counting all words) but does not explicitly position it against summarize or word_count, leaving sibling differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to pick this tool over word_count or summarize, nor any preconditions such as text length. The only usage-adjacent signal is the cost note, which is a constraint rather than routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

summarizeB

Return a short extractive summary of text. PREMIUM: consumes 1 free-quota call.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to summarize
sentencesNoMax sentences (default 3)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It usefully discloses the method (extractive, not abstractive), output brevity, and a quota cost of 1 call, which is meaningful operational context. However, it omits input length limits, truncation behavior, and any permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two crisp sentences with the core purpose front-loaded and the cost caveat trailing. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with full schema coverage and no output schema, the description covers the essential what, method, and cost. Only minor behavioral details (input size limits, failure cases) are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'text' and 'sentences' are already documented in the schema, making the baseline 3. The description's 'short' hints at the sentences default of 3 but adds no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (return) and resource (short extractive summary of text), and the word 'extractive' pins down the technique, which implicitly separates it from word_count and extract_keywords. It does not explicitly name a sibling for contrast, keeping it just 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.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over word_count or extract_keywords, and no preconditions are stated. The only qualifying note is a cost warning ('PREMIUM: consumes 1 free-quota call'), which is billing information rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

word_countB

Count words, characters, and lines in text. Free and unlimited in this sample.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to analyze

TDQS

B3.4/5.0
Behavior3/5

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 cost/quota posture ('free and unlimited in this sample'), which is useful, but says nothing about whether the operation is pure/read-only, output ordering, or how edge cases (empty text, Unicode) are handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the core capability front-loaded and no filler. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description lists the three returned metrics, which adequately covers the return values for this simple tool. Minor gaps remain around counting conventions and output shape, but nothing essential is missing for a one-parameter utility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema coverage ('Text to analyze'), so the schema already does the work. The description adds that the input yields word, character, and line counts, which clarifies what the text is measured against, but adds no format or constraint detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Count') and the exact metrics produced (words, characters, lines), so the operation is unambiguous. It does not explicitly differentiate itself from the siblings summarize or extract_keywords, but the metric-counting purpose is distinct enough to infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus summarize or extract_keywords, which also take text. 'Free and unlimited in this sample' hints at cost considerations but says nothing about selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedextract_keywords
    • First observedsummarize
    • First observedword_count
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation4/5

word_count, summarize, and extract_keywords each target a clearly different text operation, though summarize and extract_keywords overlap somewhat in that both perform content-level analysis of the same input.

Naming Consistency4/5

All names use snake_case and are readable, but the pattern varies: word_count is noun-based while summarize and extract_keywords are verb-based, so the convention isn't fully uniform.

Tool Count3/5

Three tools is on the thin side even for a sample server; the text-utility domain could reasonably support a few more operations, but the small surface is defensible given the explicit 'sample' framing.

Completeness3/5

The set covers basic text stats, summarization, and keyword extraction, but leaves obvious gaps like sentiment, readability, or other transformations, so coverage is partial rather than a full text-analysis lifecycle.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-trust-demo

    SteveMonsway
    F
    license
    Not graded
    quality
    D
    maintenance
    An intentionally vulnerable MCP server designed as a live demo target for the MCP Trust security scanner. It contains deliberate insecure patterns to demonstrate scanning capabilities.
    -

  • Reference MCP Server

    derwarre
    A
    license
    Not graded
    quality
    C
    maintenance
    A demo MCP server for validating security scanning capabilities, featuring intentional security anti-patterns such as email exfiltration, SSRF, and hardcoded fake secrets.
    364 npm
    MIT