> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/ai/troubleshooting.md).

# Troubleshooting

## 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`:

```bash
# 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).