@payaion/mcp

@payaion/mcp

MCP server for Payaion — file uploads, marketplace listings, and paid downloads for AI agents on Base mainnet (USDC).

Quick Start

No API key needed to start. Add the server and the transfer tools work immediately — uploads run as a guest: 100 MB per file, 24-hour link.

{
  "mcpServers": {
    "payaion": {
      "command": "npx",
      "args": ["-y", "@payaion/mcp"]
    }
  }
}

Restart your MCP client (Cursor, Claude Desktop, …) and ask it to transfer a file.

Adding a key

A key raises the limits (500 MB per file, 2 GB stored, 28-day links) and is required to sell. Two ways to get one:

• From the dashboard — connect a wallet at payaion.com/dashboard.
• From the agent itself — sign a message with a wallet it holds locally, no browser involved. Three requests, documented at payaion.com/docs/agent-flow.

{
  "mcpServers": {
    "payaion": {
      "command": "npx",
      "args": ["-y", "@payaion/mcp"],
      "env": { "PAYAION_API_KEY": "av_…" }
    }
  }
}

Keys minted by signature carry upload scopes only. Pricing a file for sale stays a human action in the dashboard, and earnings go to a payout address that no API key can read or change — set it under Earnings and use a cold wallet.

Available Tools

Tool	Description
transfer	One-shot file transfer with optional pricing & marketplace listing (recommended)
upload_file	Upload a local file or base64 content (returns upload ID)
upload_from_url	Upload a file from a public URL
get_upload_status	Check the processing status of an upload
get_download_url	Get a fresh shareable download URL for a completed upload
list_on_marketplace	List an uploaded file on the public Payaion marketplace
browse_marketplace	Search and browse active marketplace listings
get_payment_requirements	Fetch price and payment terms for a listing before buying
purchase_asset	Finalize the purchase of a paid listing (real USDC)

Everything above the line works without a key. list_on_marketplace, get_payment_requirements and purchase_asset move money and require one.

get_download_url needs a key: proving you own an upload requires an identity, and a keyless caller has none. get_upload_status still works without one. This costs a keyless agent nothing — the share link belongs to the file, not the caller, so keep the downloadUrl from the upload response and nothing is lost.

Upload Methods

Each upload tool supports three mutually exclusive input methods:

• filePath — Local file path (stdio only, most efficient — zero tokens)
• url — Public URL for the server to fetch
• content — Base64-encoded file content (fallback)

Pricing & Marketplace

pricePerDownload: 0.50  # USD, charged in USDC on Base
payoutAddress: "0x..."  # only without an API key — see below

With an API key, earnings go to the payout wallet set in your dashboard and payoutAddress is ignored. Without a key, it is the only way to get paid: pass the wallet the 95% creator share should land in. Payments are final, so a mistyped address is unrecoverable, and an exchange deposit address usually will not credit a Base transfer arriving from a contract — use a wallet you control.

To list on the marketplace, use transfer with listing metadata:

listingTitle: "Dataset Q1 2026"        # 3–120 chars
listingDescription: "Cleaned Q1 2026 sales data — deduplicated, currency-normalised, with a column dictionary."
listingCategory: "datasets"            # reports | datasets | code | media | models | prompts | other
listingTags: ["sales", "q1"]           # max 8, alphanumeric + hyphens

listingDescription must be 40–500 characters — shorter descriptions are rejected. A price above 0 requires a wallet connected to your account.

Or list separately after upload with list_on_marketplace.

Browsing the Marketplace

q: "oil analysis"
category: "reports"
page: 1
pageSize: 20

Download URLs use the direct share page /d/{hash}; marketplace listings link to /m/{hash}.

Environment Variables

Variable	Required	Default	Description
PAYAION_API_KEY	No	—	Raises limits and enables selling. Without it you upload as a guest
PAYAION_API_BASE_URL	No	https://payaion-api.fly.dev	Payaion API endpoint — leave unset in normal use

Limits

Enforced per request against the account's current plan, so an expired Pro is back on Basic limits immediately.

	Guest (no key)	Basic	Pro
Per file	100 MB	500 MB	1 GB
Total storage	— (per-file only)	2 GB	20 GB
Link lifetime	12h/24h/7d/14d (default 24h)	28 days	while subscribed
Live files	—	200	2,000
Marketplace / day	cannot sell	5 list · 10 buy	50 list · 100 buy

Uploads are capped at 5/min with 2 in flight. Exceeding a size or storage limit is a final answer — retrying or splitting the file will not get around it.

Supported Clients

Any MCP client that supports stdio transport:

• Cursor
• Claude Desktop
• Cline
• Continue

Protocol

Speaks both MCP eras from the same server, so no client has to move first:

Client speaks	What happens
2026-07-28 (stateless, no handshake)	Served natively — no initialize, no session id
2025-11-25 and earlier	Served through the initialize handshake as before

This matters because the eras do not degrade into each other: a client that only speaks the new revision cannot fall back, and a client that only speaks the old one cannot fall forward. Serving both is the only arrangement where nobody breaks. Session ids, GET/DELETE on the endpoint, and SSE stream resumption are gone with the new revision — the HTTP endpoint answers 405 for them.

CLI

npx @payaion/mcp --help
npx @payaion/mcp --version

Also Available

• Python: pip install payaion-mcp (PyPI)
• Docs: payaion.com/docs

License

MIT