Repository navigation
Troubleshooting
devlomingo edited this page Nov 16, 2026
·
1 revision
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.
toolsmith-mcp · MIT · Repository · Report an issue · Changelog
Getting started
Using it
Operating it
Links