MCP Server

The Payaion MCP server exposes 14 tools: uploading files, checking status, fetching download URLs, organising storage into folders, and both sides of the marketplace — listing your own files and browsing, pricing, and buying someone else's. Available as an npm package (@payaion/mcp) and a Python package (payaion-mcp).

Available tools

transferRecommended

One-shot file transfer with optional pricing and marketplace listing. Returns a shareable download URL in a single call.

Parameter	Type	Description
`filePath`	string?	Local file path (stdio mode only, zero tokens)
`url`	string?	Public URL for the server to fetch
`content`	string?	Base64-encoded file content (fallback)
`fileName`	string?	Override the file name
`mimeType`	string?	Override the MIME type
`pricePerDownload`	number?	USD price per download (0 = free)
`payoutAddress`	string?	Wallet a priced download pays out to (`0x` + 40 hex). Keyless callers only — this is what lets an agent sell with no account. Ignored when an API key is set, because that account's payout address is a dashboard setting. Payments are final.
`listingTitle`	string?	Marketplace title (3–120 chars). Auto-lists when set.
`listingDescription`	string?	What the buyer gets, 40–500 chars. Required once `listingTitle` is set
`listingCategory`	string?	reports, datasets, code, media, models, prompts, other
`listingTags`	string[]?	Up to 8 tags for discovery
`idempotencyKey`	string?	Prevent duplicate uploads on retry

Exactly one of filePath, url, or content is required. Use filePath for local files (most efficient — zero token cost).

upload_file

Low-level upload — returns immediately with an upload ID. Use get_upload_status to poll for completion.

Parameter	Type	Description
`filePath`	string?	Local file path (stdio only)
`content`	string?	Base64-encoded content
`fileName`, `mimeType`	string?	Optional overrides
`pricePerDownload`	number?	USD price per download
`payoutAddress`	string?	Wallet a priced download pays out to. Keyless callers only — ignored when an API key is set. Payments are final.
`idempotencyKey`	string?	Prevent duplicate uploads

upload_from_url

Upload a file from a public URL. Returns immediately — poll for status.

Parameter	Type	Description
`url`	string	Public HTTPS URL to fetch (required)
`fileName`	string?	Optional file name override
`pricePerDownload`	number?	USD price per download
`payoutAddress`	string?	Wallet a priced download pays out to. Keyless callers only — ignored when an API key is set. Payments are final.
`idempotencyKey`	string?	Prevent duplicate uploads

get_upload_status

Check the processing status of an upload. Returns status, ready flag, and timestamp.

Parameter	Type	Description
`uploadId`	string	The upload ID to check (required)

get_download_url

Get a fresh, shareable download URL for a completed upload. Needs an API key — it only resolves uploads on your own account. Without a key, keep the downloadUrl the upload already returned; it belongs to the file, not to the caller.

Parameter	Type	Description
`uploadId`	string	The upload ID (required)

list_on_marketplace

List a READY upload on the marketplace for public discovery and purchase.

Parameter	Type	Description
`uploadId`	string	Upload to list (required, must be READY)
`title`	string	Listing title, 3–120 chars (required)
`description`	string	What the buyer gets, 40–500 chars (required)
`tags`	string[]?	Up to 8 discovery tags
`category`	string?	reports, datasets, code, media, models, prompts, other

browse_marketplace

Search active listings. Returns title, price, seller address, file info and the page URL for each hit.

Parameter	Type	Description
`q`	string?	Keyword, matched against title and description (max 100 chars)
`category`	string?	reports, datasets, code, media, models, prompts, other
`page`, `pageSize`	number?	Defaults 1 and 20; both cap at 100

get_payment_requirements

Step one of buying. Tells you whether an asset is free and, if it is paid, returns the x402 payment requirements your wallet needs to sign.

Parameter	Type	Description
`uploadId`	string	The listed asset to price (required)

Returns isFree, an asset summary, and for paid assets a paymentRequirements object. Requires the marketplace:read scope.

purchase_asset

Step two. Submits the signed payment, settles it on Base, and returns a receipt with a download URL.

Parameter	Type	Description
`uploadId`	string	The asset to buy (required)
`paymentPayload`	object	`x402Version`, `scheme: "exact"`, `network`, and the signed `payload`

The receipt's directDownloadUrl can be fetched straight away with your X-Aion-Key header. Requires the marketplace:purchase scope.

list_storage · create_folder · update_folder · delete_folder · move_file

Folders let an agent keep an account tidy — the same tree the owner sees in the dashboard. Folders are metadata only: moving or deleting one never deletes a file, never changes a share link, price or expiry, and never changes what storage costs.

Tool	Parameters	Description
`list_storage`	`folderId?`	Every folder with its full path and file count, the files inside one folder (root when omitted), and bytes used against the plan limit
`create_folder`	`name`, `parentId?`	New folder, nested up to 8 levels deep
`update_folder`	`folderId`, `name?`, `parentId?`	Rename, re-parent, or both. `parentId: null` moves it back to the top level
`delete_folder`	`folderId`	Drops the folder and its subfolders; the files inside move back to the root
`move_file`	`uploadId`, `folderId`	Files one upload into a folder, or back to the root with `null`

Reading needs the upload:status scope; every write needs upload:create. Guest (keyless) callers have no storage, so these tools require a key.

Input methods

Upload tools accept exactly one of three input methods:

filePathRecommended

Local file path. Stdio mode only. Most efficient — the file is streamed directly without base64 encoding, using zero tokens.

url

Public HTTPS URL. The server fetches the file directly. No token cost.

content

Base64-encoded file content. Fallback for HTTP transport mode where local file access is not available. Uses tokens proportional to file size.

Transport

Both packages speak stdio, the transport every MCP client supports: npx @payaion/mcp for Node and payaion-mcp for Python. Because the server runs on your machine, filePath streams a local file straight through without spending tokens on base64.

Streamable HTTP transport is not shipped in either package. If you need a remote MCP endpoint — for a hosted agent that cannot spawn a local process — run the server yourself from apps/mcp in the repository. Over HTTP the server has no access to your filesystem, so use url or content instead of filePath.

Protocol version

Both servers speak the current MCP standard and every earlier revision, from the same code. Whichever your client implements, it works — you do not have to upgrade anything, and you are not locked out for having upgraded early.

Your client speaks	What happens
`2026-07-28`	Served natively. Stateless — every request carries its own version and capabilities, so there is no `initialize` handshake and no session id.
`2025-11-25` and earlier	Served through the `initialize` handshake, exactly as before.

Serving both matters because the two do not degrade into each other: a client on the new revision cannot fall back, and one on the old revision cannot fall forward.

Three things changed with the new revision that a client author may care about:

Sessions are gone. Mcp-Session-Id is ignored, and GET or DELETE on the HTTP endpoint return 405. Stop managing sessions; nothing replaces them.
SSE streams are not resumable. Last-Event-ID is gone. A broken stream loses the in-flight request — re-issue it with a new id.
Package floors moved. The Python package needs mcp>=2; the Node package moved off @modelcontextprotocol/sdk onto @modelcontextprotocol/server.

Environment variables

Variable	Required	Default	Description
`PAYAION_API_KEY`	Yes	—	Your API key
`PAYAION_API_BASE_URL`	No	https://payaion-api.fly.dev	API base URL

Next steps

MCP Quickstart — Setup in under 2 minutes
Marketplace & Pricing — Sell files via the marketplace
Marketplace API — Listing endpoint reference