w3storagent

MCP Server

The Model Context Protocol lets AI assistants like Claude interact with w3stor directly. Upload files, check status, and create attestations without leaving the conversation.

What is MCP?

The Model Context Protocol is an open standard that allows AI models to securely interact with external tools and data sources. Instead of copy-pasting CIDs or switching between apps, your AI assistant can store and retrieve files directly.

w3stor implements MCP over stdio transport, exposing 4 tools that map to the REST API. Payment is handled automatically via x402 -- the AI decides when to store, and the protocol handles the rest.

Setup

Claude Desktop

Add the w3stor server to your Claude Desktop configuration:

// ~/Library/Application Support/Claude/claude_desktop_config.json{  "mcpServers": {    "w3stor": {      "command": "w3stor",      "args": ["--mcp"],      "env": {        "FILECOIN_PRIVATE_KEY": "0x...",        "PINATA_JWT": "your-jwt-token"      }    }  }}

Claude Code

Register w3stor as an MCP server with a single command:

Custom MCP Client

Connect any MCP-compatible client using the SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({  command: "w3stor",  args: ["--mcp"],});
const client = new Client({ name: "my-app", version: "1.0.0" }, {});await client.connect(transport);
// List available toolsconst tools = await client.listTools();console.log(tools);
// Upload a fileconst result = await client.callTool({  name: "web3_storage_upload",  arguments: {    file: "/path/to/data.json",    tags: "dataset,v1",  },});console.log(result);

Available Tools

Each tool maps to a REST API endpoint. Tools marked x402 trigger a micropayment.

web3_storage_upload

x402
POST/upload

Upload a file to IPFS and replicate across Filecoin storage providers.

filestringrequired

Absolute path to the file to upload

tagsstring

Comma-separated tags for organization

replicationTargetnumber

Number of SP replicas (default: 3)

cidstringrequired

Content identifier (CIDv1)

sizenumberrequired

File size in bytes

pinataUrlstringrequired

IPFS gateway URL

web3_storage_list

free
GET/files

List files stored by the authenticated wallet.

statusstringquery

Filter: pinned | storing | stored

limitnumberquery

Max results (default: 50)

filesarrayrequired

Array of file objects with CID, size, status, tags

totalnumberrequired

Total count

web3_storage_status

free
GET/status/{cid}

Check replication and storage status for a specific CID.

cidstringpathrequired

Content identifier

cidstringrequired

The queried CID

statusstringrequired

pinned | storing | stored | failed

providersarray

SP providers storing this CID

replicationCountnumber

Confirmed replicas

web3_storage_attest

x402
POST/attest/{cid}

Create an on-chain attestation proving data integrity and storage.

cidstringpathrequired

CID to attest

attestationIdstringrequired

On-chain attestation ID

txHashstringrequired

Transaction hash

timestampnumberrequired

Unix timestamp