mcp-storage

Storacha MCP Storage Server exposes a decentralized storage interface for AI agents and applications. It provides tools to upload and retrieve files over the Storacha network, leveraging IPFS CIDs for verifiable data exchange. The server exposes methods such as upload to store content, retrieve to fetch content by CID/filename, and identity to expose the agent's DIDKey. Clients can connect via the MCP client in either stdio mode (default) or REST mode for cloud deployments. See the REST configuration option in the README to run the server behind an HTTP endpoint as storacha-storage-server-rest. To use the server, configure an MCP client with the storacha-storage-server entry, supply your agent private key and a delegation blob that proves permission to store data, and choose the transport mode that fits your environment.

• Upload: base64-encoded file content with a filename; optional flags include publishToFilecoin and delegation or gatewayUrl for additional routing.
• Retrieve: fetch content using a CID/filename path format, with optional multiformat base64 encoding.
• Identity: retrieve the Storacha Agent's DIDKey from your private key storage configuration.

For integration, you can reference the provided integrations guide to see code examples and SDK usage patterns, including how to wire MCP clients, Docker or other deployment targets, and how to work with delegation proofs in different runtimes.

Prerequisites:

• Node.js (LTS version) and npm or pnpm
• Access to the Storacha MCP Storage Server repository
• Optional: w3 CLI for generating credentials (as shown in the setup steps)

Installation steps:

1. Clone the repository and enter the project directory

   git clone https://github.com/storacha/mcp-storage-server.git && cd mcp-storage-server

2. Install dependencies (examples use pnpm; you can substitute with npm/yarn as needed)

   pnpm install

3. Generate keys and prepare delegation (as described in the Quick Installation Guide):

   • Install the CLI npm install -g @web3-storage/w3cli
   • Login to Storacha w3 login
   • Create a Space w3 space create <your_space_name>
   • Create a Private Key w3 key create
   • Create Delegation w3 delegation create <agent_id> --can 'store/add' --can 'filecoin/offer' --can 'upload/add' --can 'space/blob/add' --can 'space/index/add' --base64

4. Configure the MCP client to use this server by editing or supplying the configuration JSON (as shown in the README):

   { "mcpServers": { "storacha-storage-server": { "command": "node", "args": ["./dist/index.js"], "env": { "MCP_TRANSPORT_MODE": "stdio", "PRIVATE_KEY": "<agent_private_key>", "DELEGATION": "<base64_delegation>" }, "shell": true, "cwd": "./" } } }

5. Start the server using your preferred runtime (the exact command depends on how you build/dist the server). If you run in stdio mode via Node, you might execute:

   node ./dist/index.js

Note: For REST mode deployments, also prepare the REST endpoint configuration as documented in the REST configuration snippet in the README.

Tips and caveats:

• The server supports multiple transport modes. The default is stdio, but REST mode is available for cloud hosting and MCP.so compatibility; ensure your client configuration matches the transport mode you enable.
• Keep your PRIVATE_KEY and DELEGATION values secure. Do not hard-code them in source control; consider environment-based injection for production.
• If you enable REST mode, you will point MCP clients to the REST URL (for example, http://localhost:3001/rest) and provide any necessary authorization headers as per your deployment setup.
• When generating a delegation, save the recovery information and ensure you have access from other devices if needed.
• The server uses IPFS/CID-based addressing for data integrity. When uploading, verify the CID references and ensure gateways or pinning services are configured according to your storage strategy.
• If you encounter transport errors, verify that MCP_TRANSPORT_MODE matches on both server and client sides and that any required ports are open in your hosting environment.