MCP Server

Run the Pipekit CLI as a Model Context Protocol (MCP) server so that LLM clients like Claude Desktop, Cursor and Claude Code can read and modify Pipekit resources on your behalf.

The Pipekit CLI ships with a Model Context Protocol (MCP) 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).

• You have run pipekit login at least once, so that a token is on disk at ~/.pipekit/token.

• 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 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.

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

{
  "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):

{
  "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:

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:

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. 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:

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.