Troubleshooting

Common failure modes for the Pipekit MCP server and how to resolve them.

No tools appear in the client

Confirm the binary path is correct and that the client started the subprocess. Most MCP clients log the subprocess's stderr. Check there for an authentication or startup error.

If the subprocess isn't launching:

• Make sure pipekit is on the client process's PATH, not just your shell's. GUI clients (Claude Desktop, Cursor) often don't inherit your shell's PATH. Either install Pipekit to /usr/local/bin or use the absolute path in your client config.

• Check the config file syntax. JSON has no trailing commas; a missing closing brace silently disables the server in most clients.

401 unauthorized errors

For HTTP transport, first verify the request includes the correct Authorization: Bearer <token> header (--token / $PIPEKIT_MCP_TOKEN / the auto-generated value printed at startup).

If the bearer token is correct (or you are on the stdio transport), your Pipekit token has expired. Run pipekit login and try again. The next tool call picks up the new token without restarting the server.

Tools list but return errors when called

Run pipekit list clusters from the same shell. If that fails, the CLI itself is misconfigured (network, login, permissions) and the MCP server will fail in the same way. Fix the CLI first; the MCP server will start working automatically.

Agent has access to wrong Organization

The MCP server uses the CLI token on disk. Running pipekit login against a different Organization switches the token; subsequent tool calls reflect the new context.

If you want one agent connected to Org A and another to Org B simultaneously, point each at a separate token store via $PIPEKIT_CONFIG_DIR:

# Org A agent
PIPEKIT_CONFIG_DIR=~/.pipekit-org-a pipekit mcp

# Org B agent
PIPEKIT_CONFIG_DIR=~/.pipekit-org-b pipekit mcp

Run pipekit login once against each PIPEKIT_CONFIG_DIR to populate the corresponding token.

Tools the agent calls don't return the latest data

Pipekit doesn't cache between tool calls. Every call hits the live API. If the agent shows stale data, it's caching the result in its own conversation context. Ask the agent to re-fetch (call list_runs or get_run again).