Skip to main content
Glama
Payload Sample MCP Server

Payload Sample MCP Server

Official
by Payloadhq

Payload Sample MCP Server by Payload

A free sample by Payload - companion to the MCP Monetization Engine.

A real, installable MCP server (official mcp Python SDK, stdio transport) that demonstrates the core mechanic of Payload's paid MCP Monetization Engine: 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 Engine 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+.

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

Or run it in Docker (no Python needed)

docker build -t payload-sample-mcp-server .
docker run -i --rm 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"
    }
  }
}

Use it in Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

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

Restart Windsurf; the server appears under MCP servers with its free and premium (quota-metered) tools.

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 Engine ($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 Veyline Developer Primer ($79) (formerly the x402 Paid API Starter Kit) 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, 46 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


More from Payload · payloadhq.github.io · all Payload repos

Related: mcp-monetization-kit · mcp-monetization-demo · mcp-readiness-check

Available Tools

3 tools
extract_keywordsB

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

Inputs: text (required), limit.

summarizeB

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

Inputs: text (required), sentences.

word_countB

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

Inputs: text (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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.
      -