AI agents & MCP

Give AI agents durable, content-addressed file storage on IPFS via our first-party MCP server. Works with Claude Code, Cursor, Windsurf, and Claude Desktop out of the box.

IPFS Ninja MCP server working in Claude Code

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools. An MCP server exposes typed tools that an LLM can call during a conversation — the client (Claude Code, Cursor, Windsurf, Claude Desktop) discovers the tools at startup and passes them to the model.

Our MCP server, published on npm as @ipfs-ninja/mcp-server, exposes 12 tools that map one-to-one to our REST API. The agent uploads, pins, lists, and retrieves IPFS content by name — no glue code, no HTTP boilerplate.

Why content-addressed storage for agents

Agent memory built on a vector DB is bound to a specific embedding model — swap the model and every vector is meaningless. Content-addressed storage (IPFS CIDs) gives agents:

Model-agnostic pointers — the same bytes always produce the same CID, regardless of which agent, prompt, or LLM produced them.
Verifiable retrieval — the CID is a hash; you can recompute it from bytes and confirm nothing was tampered with.
Portable handoff — Agent A hands a CID to Agent B via any medium (a JSON file, an event bus). No shared schema required.
Auditable — CIDs point to immutable bytes; you can inspect exactly what the agent remembered.

Use IPFS as the durable source of truth; layer vector search on top for retrieval. See the companion blog post for the full pattern.

Endpoint

The MCP server runs locally via npx — there is no hosted MCP endpoint to point at. The client spawns npx -y @ipfs-ninja/mcp-server as a subprocess, and the server calls our REST API at https://api.ipfs.ninja with the bearer key held in your config.

Transport: stdio
Command: npx -y @ipfs-ninja/mcp-server
Auth: IPFS_NINJA_API_KEY env var (bearer key held server-side, never exposed to the model)

Tools

The server exposes 12 tools grouped by concern:

File operations

Tool	Purpose
`ipfs_upload`	Upload file content (base64 or text)
`ipfs_upload_json`	Upload a JSON object as a permanent file
`ipfs_import_car`	Import a CAR file (DAG import)
`ipfs_list`	List your uploaded files, filterable by time range
`ipfs_get`	Get file metadata for a CID
`ipfs_delete`	Unpin and delete a file from your account

Pinning

Tool	Purpose
`ipfs_pin`	Pin an existing IPFS CID to your account
`ipfs_pin_status`	Check pin progress

Organisation

Tool	Purpose
`ipfs_folders_list`	List your folders
`ipfs_folders_create`	Create a new folder

Account

Tool	Purpose
`ipfs_profile`	Plan, storage bytes, bandwidth used
`ipfs_analytics`	Daily bandwidth and file stats

Every tool returns a JSON payload matching the corresponding REST response. See MCP Server for full input/output schemas.

Setup

Claude Code

One command:

bash

claude mcp add ipfs-ninja \
  --transport stdio \
  -e IPFS_NINJA_API_KEY=bws_your_full_api_key_here \
  -- npx -y @ipfs-ninja/mcp-server

Restart Claude Code and run /mcp to verify.

Cursor / Windsurf

Open Settings > MCP Servers > Add Server:

Field	Value
Name	`ipfs-ninja`
Transport	`stdio`
Command	`npx`
Args	`-y @ipfs-ninja/mcp-server`
Env	`IPFS_NINJA_API_KEY=bws_...`

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json

{
  "mcpServers": {
    "ipfs-ninja": {
      "command": "npx",
      "args": ["-y", "@ipfs-ninja/mcp-server"],
      "env": {
        "IPFS_NINJA_API_KEY": "bws_your_full_api_key_here"
      }
    }
  }
}

Fully quit and relaunch.

Security

API key handling

The IPFS_NINJA_API_KEY env var is passed as an X-Api-Key bearer header on every REST call to api.ipfs.ninja. It stays on your local machine — the MCP transport does not forward env vars to the LLM. The model only sees tool names and parameters, not the credential.

Key rotation

Keys don't expire, but you can revoke and rotate them at any time from the API Keys dashboard. Create separate keys per environment (dev / staging / prod) so you can revoke one without affecting the others.

Scope

There is no per-tool scoping today — a key with API access can call every MCP tool. If you need to hand a limited-scope credential to a client-side agent, use signed upload tokens instead of the raw API key; those are time-limited and scoped to upload operations only.

Privacy

IPFS itself is public — anyone with the CID can retrieve the file from any gateway that has it pinned. If your agent handles sensitive data, encrypt payloads before uploading (AES-256 or your preferred sealed-box scheme) and store the decryption key on your side. The CID then points to opaque ciphertext.

Troubleshooting

See the MCP Server API reference for common errors (IPFS_NINJA_API_KEY environment variable is required, API error 402, API error 403, and "server not showing in /mcp").

MCP Server API reference — full input/output shapes
Authentication — API keys, JWT, signed tokens
Blog: IPFS storage for AI agents — the "why" behind content-addressed agent memory
Blog: Claude Code + MCP tutorial — 5-minute copy-paste setup

AI agents & MCP ​

What is MCP? ​

Why content-addressed storage for agents ​

Endpoint ​

Tools ​

File operations ​

Pinning ​

Organisation ​

Account ​

Setup ​

Claude Code ​

Cursor / Windsurf ​

Claude Desktop ​

Security ​

API key handling ​

Key rotation ​

Scope ​

Privacy ​

Troubleshooting ​

Related ​