Payload Sample MCP Server
OfficialA sample MCP server that demonstrates per-tool-call metering: free text utilities plus premium tools with a free quota, returning PAYMENT_REQUIRED after exhaustion without collecting real payment.
word_count— free and unlimited: counts words, characters, and lines in text.summarize— premium: returns an extractive summary; optionalsentences(default 3); consumes 1 free-quota call.extract_keywords— premium: returns most frequent significant words; optionallimit(default 10); consumes 1 free-quota call.Premium tools share a free quota (default 5 calls,
PAYLOAD_FREE_QUOTA), then return a machine-readable x402-stylePAYMENT_REQUIREDJSON payload.A hard cap (default 200 total calls,
PAYLOAD_HARD_CAP) limits use; metering is in-memory and resets on restart.Does not collect real payments; proves the paid MCP Monetization Engine mechanic.
Runs locally via pip or Docker and can be configured in Claude Desktop, Cursor, or Windsurf.
Intentionally unauthenticated; security hardening and real payment collection are in Payload's paid kits.
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 |
| FREE, unlimited | Count words, characters, and lines of input text. |
| PREMIUM | Naive extractive summary of text. |
| 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-serverOr run it in Docker (no Python needed)
docker build -t payload-sample-mcp-server .
docker run -i --rm payload-sample-mcp-serverUse 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/x402manifest generator, HMAC + facilitator verifiers, append-only usage ledger, working example server, 46 automated tests. Non-custodial by design.
Payload ecosystem
All Payload products - https://payloadtools.gumroad.com
More Payload repos - https://github.com/Payloadhq
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 toolsextract_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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
A paid remote MCP for CLI tool MCP, built to return verdicts, receipts, usage logs, and audit-ready
Experimental MCP server for current empirical verification of explicit public HTTPS endpoint claims.
A paid remote MCP for hosted MCP server, built to return verdicts, receipts, usage logs, and audit-r
Scan any MCP server for tool-poisoning, security, auth & license. Trust score before install.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA deliberately insecure MCP server designed as a pentest lab to demonstrate common vulnerabilities in MCP deployments.-
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server template with OAuth 2.1, RBAC, and audit logging for building secure, observable tool servers.MIT
- AlicenseNot gradedqualityCmaintenanceA demo MCP server for validating security scanning capabilities, featuring intentional security anti-patterns such as email exfiltration, SSRF, and hardcoded fake secrets.ISC