addCidToPaymentInstruction
Associate a CID with a payment instruction for x402 monetization
LABSCO SUMMARY
The same CID can be stored, signed, charged for and searched by meaning without leaving the client.
The payment side is narrower than the storage side: createPaymentInstruction and updatePaymentInstruction state support for USDC with 6 decimals on Base and Base Sepolia only. Semantic search is opt-in per file — queryVectors reaches a group's files after vectorizeFile has run on them, not the whole account. Local uploads are fenced to the directories listAllowedDirectories returns, which is worth checking before pointing uploadFile at a path.
What it is
A Pinata account front end covering 35 tools, spanning IPFS uploads and gateway reads, file groups, x402 payment instructions, EIP-712 signatures and vector search.
What you get
- Files end to end: uploadFile takes either a file:// URI or base64 content, searchFiles filters by name, CID or MIME type, getFileById returns the detail, updateFile edits the name and key-value pairs, and deleteFile removes it.
- Links sized to the audience: createLink returns a gateway URL for a public file and a temporary download link for a private one, createPrivateDownloadLink issues the timed link directly, and fetchFromGateway returns the content itself.
- Grouping as the unit of organisation: createGroup, listGroups, getGroup, updateGroup and deleteGroup, with addFileToGroup and removeFileFromGroup moving files between them.
- Content already on IPFS: pinByCid pins an existing CID into the account with optional host_nodes and metadata, queryPinRequests reports where each request stands, and cancelPinRequest drops a pending one.
- Paid access to a CID: createPaymentInstruction sets an amount in USDC and a pay_to address, addCidToPaymentInstruction and removeCidFromPaymentInstruction control what it covers, and listPaymentInstructions, getPaymentInstruction, listPaymentInstructionCids, updatePaymentInstruction and deletePaymentInstruction handle the rest.
- Provenance and semantic lookup: addSignature attaches an EIP-712 signature to a CID with getSignature and deleteSignature alongside it, while vectorizeFile, queryVectors and deleteFileVectors give a group a text query that matches on meaning.
- Uploads that do not go through the client: createSignedUploadUrl issues a URL constrained by allow_mime_types, max_file_size and an expiry, so a browser can upload without holding the API key.
Requirements
A Pinata account and a working Pinata JWT — testAuthentication is the call that confirms it. Uploads from the local machine read only the directories that listAllowedDirectories reports, and a payment instruction needs an address to pay to.
Setup effort
One command plus credentials — npx -y pinata-mcp, then supply credentials
USE CASES
01
Handing someone a file without making it public
Upload it, then issue a link that expires instead of a permanent gateway URL. Public files get the gateway URL from the same call.
02
Charging for access to something you already pinned
Create the payment instruction once, then attach and detach the CIDs it covers as the content changes.
03
Finding a file you uploaded months ago and cannot name
Filename search covers the case where you remember the name. When you only remember what was in it, vectorize the candidates and query the group by meaning.
04
Letting a browser upload straight to storage
Issue a signed URL bounded by MIME type, size and expiry so the client uploads directly, then file what arrives into a group.
05
Showing that a file came from the address it claims
Attach a signature to the CID and read it back later, so the claim travels with the content rather than with the link.
06
Bringing a CID someone else pinned into your own account
Pin the existing CID, watch the request until it settles, and cancel it if it stalls or was a mistake.
35 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
addFileToGroup
Add an existing file to a group in your Pinata account
addSignature
Add an EIP-712 cryptographic signature to a CID for content verification
cancelPinRequest
Cancel a pending pin by CID request
createGroup
Create a new group in your Pinata account to organize files
createLink
Create a direct access link for a file stored on Pinata IPFS. For public files returns a gateway URL, for private files generates a temporary download link.
createPaymentInstruction
Create a new x402 payment instruction for content monetization. Currently supports USDC (6 decimals) on Base/Base Sepolia only.
createPrivateDownloadLink
Generate a temporary download link for accessing a private IPFS file from Pinata
createSignedUploadUrl
Create a signed URL for client-side file uploads without exposing your API key
deleteFile
Delete a file from your Pinata account by its ID
deleteFileVectors
Delete vectors for a file
deleteGroup
Delete a group from your Pinata account by its ID
deletePaymentInstruction
Delete an x402 payment instruction
deleteSignature
Remove a signature from a CID
fetchFromGateway
Fetch content from Public or Private IPFS via Pinata gateway and return it
getFileById
Retrieve detailed information about a specific file stored on Pinata by its ID
getGroup
Retrieve detailed information about a specific group by its ID
getPaymentInstruction
Retrieve a specific x402 payment instruction by ID
getSignature
Get signature details for a specific CID
listAllowedDirectories
List all directories that this MCP server is allowed to access for file operations
listGroups
List groups in your Pinata account with optional filtering by name
listPaymentInstructionCids
List CIDs associated with a payment instruction
listPaymentInstructions
List and filter x402 payment instructions for content monetization
pinByCid
Pin an existing CID from the IPFS network to your Pinata account
queryPinRequests
Query the status of pin by CID requests
queryVectors
Query vectorized files in a group using semantic search
removeCidFromPaymentInstruction
Remove a CID association from a payment instruction
removeFileFromGroup
Remove a file from a group in your Pinata account
searchFiles
Search for files in your Pinata account by name, CID, or MIME type. Returns a list of files matching the given criteria.
testAuthentication
Verify that your Pinata JWT is valid and working
updateFile
Update metadata for an existing file on Pinata including name and key-value pairs
updateGroup
Update metadata for an existing group on Pinata
updatePaymentInstruction
Update an existing x402 payment instruction. Currently supports USDC (6 decimals) on Base/Base Sepolia only.
uploadFile
Upload a file to Pinata IPFS. Provide either a file:// URI or base64-encoded content.
vectorizeFile
Vectorize a file for AI/semantic search capabilities
BEFORE YOU INSTALL
What to know first
Tools you get
35 tools when we connected.
Requires
- npx on PATH
- Node.js 18+
- PINATA_JWT in your environment
- GATEWAY_URL in your environment (your Pinata gateway domain)
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 35 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y pinata-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"pinata": {
"command": "npx",
"args": [
"pinata-mcp",
"<YOUR_PATH_TO_ALLOWED_DIRECTORY>",
"<YOUR_PATH_TO_ANOTHER_ALLOWED_DIRECTORY>"
],
"env": {
"PINATA_JWT": "<YOUR_JWT>",
"GATEWAY_URL": "example.mypinata.cloud"
}
}
}
}<YOUR_JWT> is your Pinata API key (JWT). example.mypinata.cloud is a sample; yours is your own Pinata gateway domain. The directory arguments are optional: without them the server can only read files in its current working directory, so list every folder uploadFile should read from.
Claude Code
Run this in a terminal. It registers the server for all your projects; use --scope project instead to register it for the current project only.
CLAUDE CODE · TERMINAL
claude mcp add pinata --scope user --env PINATA_JWT=<YOUR_PINATA_JWT> --env GATEWAY_URL=example.mypinata.cloud -- npx pinata-mcp <YOUR_PATH_TO_ALLOWED_DIRECTORY><YOUR_PINATA_JWT> is your Pinata API key (JWT), and <YOUR_PATH_TO_ALLOWED_DIRECTORY> is a folder uploadFile may read from. example.mypinata.cloud is a sample; yours is your own Pinata gateway domain. The directory is optional: without it the server can only read files in its current working directory.
