MCP Troubleshooting

Use this page when an MCP tool fails, the agent calls the wrong tool, schema validation behaves unexpectedly, or a MeshKit provider error appears after tool input passes validation.

Start by logging the tool name, scope, sanitized input shape, and MeshKit error code. Do not log raw content or secrets.

Fast Triage

Symptom	Likely cause	Fix
Tool is missing	Host did not register it or filtered it from the allowlist.	Compare the exposed tool list with `createMeshkitMcpTools()`.
`invalid_tool_input`	Input is not an object, is missing a required field, or a field is not a string.	Validate against the tool's schema before calling `run`.
`input_too_large`	A string exceeds a runtime byte limit.	Store larger data through the SDK and pass the resulting CID.
Unknown fields are accepted	Host is not enforcing `additionalProperties: false`.	Reject unknown fields before calling `run`.
`expiresIn` accepts unexpected text	Host is not enforcing the schema pattern.	Enforce `^[0-9]+[mhd]$` in host validation.
Proof inspection fails	CID belongs to a different provider or metadata environment.	Use the same MeshKit client environment that created the CID.
Share fails for a recipient	Recipient identity is missing or not authorized.	Create or resolve the recipient identity before sharing.

Validation Errors

`invalid_tool_input`

The tool runtime throws this when input is not a JSON object or a required string field is missing or has the wrong type.

Example bad input:

await put.run("store this");

Example fixed input:

await put.run({
  content: "store this",
});

`input_too_large`

The runtime byte limits are intentionally small enough for agent tool calls:

meshkit.files.put.content: 1048576 bytes.
CIDs, names, recipients, identity IDs, and content types have smaller field limits.

For larger payloads, the application should store the data through MeshKit directly and let the agent operate on the CID.

Host Policy Errors

Some failures should be blocked by the host before MeshKit runs:

Tool not on the workflow allowlist.
Unknown input fields.
expiresIn outside the accepted pattern.
Missing human approval for identity creation or sharing.
Agent attempting to choose provider config or tokens.

Return a host-policy error to the agent instead of calling tool.run.

MeshKit Provider Errors

After validation passes, the underlying MeshKit client can still fail. Common causes:

Error family	Cause	Fix
Provider HTTP errors	Endpoint, token, timeout, or network failure.	Run `meshkit providers test --json` with the same provider environment.
Proof errors	CID metadata is missing or belongs to another environment.	Check metadata service URL and app ID.
Identity errors	Recipient identity is missing or not resolvable.	Create or resolve the identity before sharing.
Share errors	Capsule cannot be created or authorization fails.	Confirm recipient, expiry, policy, and provider support.
Key unwrap errors	Current identity cannot open the object.	Confirm the share capsule and wrapped key are present.

Safe Error Responses

Return enough information for the agent to recover:

import { MeshKitError } from "@meshkit/meshkit";

try {
  return await tool.run(input);
} catch (error) {
  if (error instanceof MeshKitError) {
    return {
      ok: false,
      code: error.code,
      suggestion: error.suggestion,
    };
  }

  return {
    ok: false,
    code: "tool_error",
    suggestion: "Check the MeshKit MCP host logs.",
  };
}

Keep detailed provider errors in trusted logs with secrets redacted.

Debug Checklist

Confirm the host exposed only the intended tool names.
Print tool.inputSchema for the failing tool.
Validate the input object in host code.
Confirm the injected MeshKitClient uses the intended provider and app ID.
Run npx -p @meshkit/cli meshkit doctor --json against the same provider configuration.
Check proof metadata with meshkit.inspect for the exact CID.
Confirm human approval was recorded for identity or share actions.

MCP Troubleshooting

On this page