MCP Troubleshooting

Start with the exact command configured in your MCP client. Run it from a normal terminal so startup errors written to stderr are visible:

/absolute/path/to/project/node_modules/.bin/runable mcp --cwd /absolute/path/to/project

The process waiting silently is normal: after startup, it expects MCP messages on stdin.

@runablejs/mcp is not installed

Error:

No @runablejs/mcp installation found for project "...".

Install it in the project passed to --cwd:

pnpm add -D @runablejs/mcp

Do not rely on a copy installed in another workspace package or globally. runable mcp resolves it from the target project.

No Runable installation found

The MCP package was found, but runable could not be resolved from the inspected project.

Check that:

• --cwd points to the project root containing package.json;
• runable is a dependency of that project;
• dependencies have been installed;
• the MCP client uses the expected absolute path.

Inspector is incompatible

If the error says that runable/inspector is unavailable or names a missing Inspector method, upgrade the project's Runable version:

pnpm update runable

Check the supported combinations in Compatibility. If only resolve_route fails, the project may have base compatibility while the remaining tools continue to work.

Failed to create the Inspector

This means Runable found the project but could not resolve its configuration. Run the project's normal preparation or build command to expose the underlying configuration error:

runable prepare

Fix errors in runable.config.* or module setup() hooks, then restart the MCP connection.

The client shows no tools

Check these items:

1. The client configuration uses a local stdio server, not an HTTP URL.
2. command points to an existing executable.
3. Both command and --cwd use correct absolute paths.
4. The client has been restarted or its MCP configuration reloaded.
5. Organization policy allows local MCP servers.

Run the client's MCP listing command when available. A connected Runable server exposes eight tools.

Project data is stale

The server keeps one Inspector instance for the connection. After changing pages, layouts, middleware, plugins, modules, or configuration, ask the agent to call:

refresh

Then call get_routes, get_config, or get_extensions again. Other tools do not refresh automatically.

The wrong project is inspected

Call get_project and inspect rootDir. If it is wrong, update both the executable path and the value passed to --cwd in the client configuration.

Protocol errors or invalid JSON

stdout belongs exclusively to MCP after the server starts. If a wrapper script, shell profile, or custom integration prints status text to stdout, it can corrupt the protocol.

Use the direct project executable and send diagnostics to stderr. Runable already redirects output produced by project configuration while the Inspector is resolving it.

search_api returns an unexpected version

The result includes both documentationVersion and projectRunableVersion. They can differ because the documentation index ships with the MCP package while inspection uses the project's Runable package.

Upgrade @runablejs/mcp for a newer documentation index, or use the returned versions to account for the difference before applying an API example.