Skip to content

Troubleshooting

devlomingo edited this page Nov 16, 2026 · 1 revision

Troubleshooting

Run toolsmith-mcp doctor first. It checks the Node version, config, tokens, integrations and upstream connections, and says what to fix.

Symptom Fix
Environment variable X is not set Add X=... to the .env next to the config, or export it.
The spec does not say where the API is hosted Pass --base-url https://….
Blocked request: … private address The API is local or private. If intended, set "allowPrivateNetwork": true for that integration only.
The API rejected the credentials (401) The token is missing, wrong or expired. Update the named variable and restart.
… does not match its documented schema The API returns something its spec doesn't describe. Fix the spec, or set "validateOutput": false for that integration.
Evaluation failed toolsmith-mcp show <name> lists the failing checks. Fix them and run evaluate <name>.
Composite fails with "no example input" toolsmith-mcp evaluate <name> --input '{"userId": 1}' with a real value.
A tool isn't visible to the agent Not published, or a write/destructive tool that wasn't granted. Check toolsmith-mcp list.
A composite disappeared One of its step tools was disabled or lost its grant. list shows the reason.
Every upstream tool call needs approval The server doesn't annotate its tools, so they count as destructive. Add read-only ones to trustedTools.
… needs a person at an interactive terminal Granting commands need a typed yes. Use the dashboard for scripted or remote approval.
No workflows found Fewer than 3 sessions ran it, or the calls aren't linked by data. Over HTTP, send X-Toolsmith-Session.
Refusing to serve MCP over HTTP … without a client token Run toolsmith-mcp init or set server.mcpToken.
Dashboard rejects the token Use TOOLSMITH_ADMIN_TOKEN, not the MCP token. start prints a sign-in link.
HTTP 403 from /mcp in a browser Cross-origin requests are refused on purpose. Use an MCP client.
npm install -g github:… fails Install from npm or a release tarball instead.

Still stuck? Open an issue with the doctor output. Check it for anything private before posting.

Clone this wiki locally