Tools

@meshkit/mcp currently exposes four tools. Keep the exposed set smaller than the available set whenever the agent workflow allows it.

Each tool has a declared scope, JSON-schema-like inputSchema, and run(input) function. The host should use the schema to guide model calls and enforce policy before execution.

Catalog

Tool	Scope	Required input	Output	Main risk
`meshkit.files.put`	`files:write`	`content`	`MeshFile`	Agent stores sensitive plaintext supplied in tool input.
`meshkit.inspect`	`proofs:read`	`cid`	`MeshProof`	Agent learns proof metadata for a CID.
`meshkit.identity.create`	`identity:write`	`id`	MeshKit identity public key object	Agent creates identities that may later receive shares.
`meshkit.share.with`	`share:write`	`cid`, `recipient`	`ShareCapsule`	Agent grants future access to encrypted content.

`meshkit.files.put`

Stores string content through mesh.files.put.

await tool.run({
  name: "agent-object",
  content: "text to encrypt",
  contentType: "text/plain",
});

Inputs:

Field	Required	Default	Runtime limit
`content`	Yes	None	1048576 UTF-8 bytes
`name`	No	`agent-object`	256 UTF-8 bytes
`contentType`	No	`text/plain`	128 UTF-8 bytes

Use this for small text payloads only. For larger files, write through an application-controlled SDK workflow and give the agent the resulting CID.

`meshkit.inspect`

Returns proof metadata for a CID.

await tool.run({
  cid: "bafy...",
});

Inputs:

Field	Required	Runtime limit
`cid`	Yes	256 UTF-8 bytes

Inspection does not decrypt content. It answers whether MeshKit proof metadata is available for the CID in the configured environment.

`meshkit.identity.create`

Creates a local MeshKit recipient identity.

await tool.run({
  id: "alice",
});

Inputs:

Field	Required	Runtime limit
`id`	Yes	128 UTF-8 bytes

Treat identity creation as a controlled operation. The MCP package does not verify that alice maps to a real user, account, wallet, DID, email address, or passkey.

`meshkit.share.with`

Creates a share capsule for a CID and recipient through mesh.share.file(cid).with(recipient, options).

await tool.run({
  cid: "bafy...",
  recipient: "alice",
  expiresIn: "2h",
});

Inputs:

Field	Required	Runtime limit
`cid`	Yes	256 UTF-8 bytes
`recipient`	Yes	128 UTF-8 bytes
`expiresIn`	No	16 UTF-8 bytes

The schema advertises expiresIn as a string matching ^[0-9]+[mhd]$. If your MCP transport does not enforce schemas before calling run, enforce that pattern in your host approval layer.

Sharing controls future MeshKit opens. It cannot erase plaintext already decrypted or copied by a recipient.

Tool Selection Patterns

Agent workflow	Tools to expose
Store agent-generated notes and inspect proof metadata	`meshkit.files.put`, `meshkit.inspect`
Inspect known CIDs only	`meshkit.inspect`
Prepare shares with human approval	`meshkit.inspect`, `meshkit.share.with`
Onboard recipients in an admin flow	`meshkit.identity.create` plus explicit admin approval

Do not expose meshkit.share.with just because the agent can store content. Sharing is a separate permission.

Error Behavior

Tool validation can throw:

invalid_tool_input when input is missing, not an object, or a required field is not a string.
input_too_large when a runtime byte limit is exceeded.

The underlying MeshKit client may also throw provider, proof, identity, sharing, or authorization errors.

On this page