Tools reference

MCP tools exposed by @ipfs-meshkit/mcp, including encrypted upload and retrieve.

`ipfs_upload`

Upload text or base64-encoded binary content to IPFS. Returns the CID. Optional password encrypts with AES-256-GCM (PBKDF2-SHA256) before the bytes are sent to Kubo.

Input (one of content or base64 is required):

{ "content": "Hello, IPFS!" }

{ "base64": "aGVsbG8=" }

Encrypted upload — this is Alice publishing a file only Bob can read. The CID names the ciphertext. Share the password with Bob outside the tool call; it is not stored on IPFS.

{
  "content": "confidential manifest data",
  "password": "correct-horse-battery-staple",
  "pbkdf2Iterations": 200000
}

Field	Required	Description
`content`	One of	UTF-8 text to upload.
`base64`	One of	Base64-encoded binary to upload.
`password`	No	If set, content is encrypted before upload. Only someone with this password can decrypt.
`pbkdf2Iterations`	No	PBKDF2-SHA256 rounds. Default `200000`. Must be ≥ 1,000. Higher is slower and harder to guess offline.

Output:

{
  "cid": "Qm...",
  "encrypted": true
}

encrypted is false when password was omitted.

`ipfs_retrieve`

Retrieve content from IPFS by CID. Pass password when the object was uploaded encrypted — this is Bob opening the file Alice published.

Input:

{ "cid": "Qm..." }

Decrypt:

{
  "cid": "Qm...",
  "password": "correct-horse-battery-staple"
}

Field	Required	Description
`cid`	Yes	IPFS CID to retrieve.
`password`	No	Decrypts an EMSH payload from an encrypted upload. Omit to receive the raw bytes.

Output:

{
  "cid": "Qm...",
  "content": "confidential manifest data",
  "encoding": "text"
}

encoding is "text" when the bytes are valid UTF-8, and "base64" otherwise. An EMSH blob retrieved without password comes back as base64 in content. A wrong password returns a tool error (Decryption failed: wrong password or corrupted data).

Alice and Bob through an agent

Ask the agent to publish as Alice, then to read as Bob. The password stays in the tool arguments on each machine. It is not part of the IPFS object.

Alice's agent calls ipfs_upload with content (or base64) and password.
The tool returns { cid, encrypted: true }. That CID is what gets shared on the network.
Bob's agent calls ipfs_retrieve with that cid and the same password.
The tool returns the original text. An agent that retrieves the CID without password gets the ciphertext, with encoding: "base64".

`ipfs_pin`

Pin a CID on the node to prevent garbage collection.

Input:

{ "cid": "Qm..." }

Output: Confirmation message.

`ipfs_list_pins`

List all pinned CIDs on the primary node.

Input: None

Output: Array of CID strings.

`ipfs_publish_name`

Publish an IPNS record pointing at a CID or /ipfs/... path.

Input:

{
  "value": "Qm...",
  "key": "latest",
  "ttl": "1m",
  "lifetime": "24h"
}

Field	Required	Description
`value`	Yes	CID or `/ipfs/...` path to publish.
`key`	No	Keystore label. Defaults to `"self"`.
`ttl`	No	Cache hint for resolvers.
`lifetime`	No	Record validity window.

Output: IPNS name and published path.

`ipfs_resolve`

Resolve an IPNS name and retrieve the content bytes.

Input:

{ "name": "/ipns/Qm..." }

Output: Resolved content as text or base64.

`ipfs_generate_key`

Create a named IPNS signing key in the node's keystore.

Input:

{ "name": "my-key" }

Output: Key ID (stable IPNS name) and key name.

`ipfs_list_keys`

List all IPNS keys in the node's keystore.

Input: None

Output: Array of { id, name } objects.

Tools reference

On this page