# MCP Server

The Pipekit CLI ships with a Model Context Protocol ([MCP](https://modelcontextprotocol.io/)) server. When you run `pipekit mcp`, the CLI exposes its capabilities as MCP tools and resources that any MCP-compatible LLM client can call.

## Prerequisites

* The Pipekit CLI installed (see the [CLI installation instructions](/cli.md#installation)).
* You have run `pipekit login` at least once, so that a token is on disk at `~/.pipekit/token` (or `$PIPEKIT_CONFIG_DIR/token` if that env var is set).
* An MCP-capable LLM client (Claude Desktop, Cursor, Claude Code, Goose, etc.).

The MCP server reads your token fresh on every authenticated tool call. If your token expires, run `pipekit login` again — the next tool call picks up the new token without restarting the server.

## Transports

The CLI supports two transports:

* **stdio** *(default)* — the LLM client launches `pipekit mcp` as a subprocess and talks to it over stdin/stdout. This is the configuration described below and is the recommended path for local LLM-client integrations.
* **HTTP** *(opt-in)* — `pipekit mcp --transport=http` runs an HTTP server speaking [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) for clients that don't fork subprocesses.

The HTTP transport defaults to binding `127.0.0.1:8080` and refuses to bind a non-loopback address unless you also pass `--allow-remote`. Every HTTP request must carry an `Authorization: Bearer <token>` header. The token is taken from `--token`, then from `$PIPEKIT_MCP_TOKEN`, otherwise the server generates a fresh 32-byte hex token at startup and prints it to stderr. Loopback binds additionally apply a Host-header allowlist (matching the bind-side loopback rule) to defend against [DNS rebinding](https://en.wikipedia.org/wiki/DNS_rebinding_attack).

```bash
# loopback HTTP (default address; token is generated and printed)
pipekit mcp --transport=http

# explicit loopback IP and operator-supplied token
PIPEKIT_MCP_TOKEN=$(openssl rand -hex 32) pipekit mcp --transport=http --addr=127.0.0.1:9000

# bind a non-loopback interface (LAN/container); requires opt-in
pipekit mcp --transport=http --addr=0.0.0.0:8080 --allow-remote
```

## Tool inventory

Tools are annotated with the MCP `readOnlyHint` and `destructiveHint` hints so compatible clients (Claude Desktop, Cursor, Claude Code) can render appropriate warnings or apply approval policies. Read-only tools (`list_*`, `get_*`, `version`) carry `readOnlyHint: true`. State-changing tools default to `destructiveHint: true`; additive tools that only create new resources (`submit_workflow`, `create_cron`, `trigger_cron`, `restart_run`, `import_workflows`) carry `destructiveHint: false`.

For the live list of tools and their schemas, ask your client to introspect the MCP server. The server also publishes a library of reference resources (Argo workflow schemas, Argo examples, Pipekit guides) that LLM clients can list and read on demand.

## Configuration recipes

The following snippets all assume the `pipekit` binary is on your `PATH`. If it is not, replace `pipekit` with the absolute path (e.g. `/usr/local/bin/pipekit`).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "pipekit": {
      "command": "pipekit",
      "args": ["mcp"]
    }
  }
}
```

Restart Claude Desktop. The Pipekit tools will appear under the tool/plug icon in the prompt area.

### Cursor

Edit `~/.cursor/mcp.json` (or the project-scoped `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pipekit": {
      "command": "pipekit",
      "args": ["mcp"]
    }
  }
}
```

Reload the Cursor window. Pipekit tools become available to the agent.

### Claude Code

The recommended path is the CLI command, which writes the configuration to `~/.claude.json` (user scope) for you:

```bash
claude mcp add pipekit pipekit mcp
```

For project-scoped configuration, create or edit `.mcp.json` in the project root with the same `mcpServers` block shown above for Claude Desktop and Cursor.

### Generic MCP-compatible client

Any client that supports the stdio transport can run the server directly. The minimum command is:

```bash
pipekit mcp
```

The server speaks newline-delimited JSON-RPC over stdio per the MCP specification.

## Authentication and identity

Tools call into the same Pipekit APIs the CLI itself uses. Each call runs with the identity of the user whose token is at `~/.pipekit/token` (or `$PIPEKIT_CONFIG_DIR/token` if that env var is set). If you switch organizations with `pipekit login`, subsequent tool calls reflect the new context.

There is no per-tool approval gate built into the stdio server itself — that policy lives in the LLM client. Clients that honour MCP tool annotations prompt before calling tools annotated with `destructiveHint: true`, so the per-tool annotations described above feed their built-in confirmation flows.

## Logging

`pipekit mcp` honours the same `--log-level` and `--log-format` flags as the rest of the CLI:

```bash
pipekit mcp --log-level=debug --log-format=json
```

Logs go to stderr so they do not interfere with the MCP protocol stream on stdout.

## Troubleshooting

* **No tools appear in the client.** Confirm the binary path is correct and that the client started the subprocess. Most clients log the subprocess's stderr — check there for an authentication error.
* **`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 client lists tools but they 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pipekit.io/cli/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.