> 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/setup.md).

# Setup

Run the Pipekit CLI as a Model Context Protocol ([MCP](https://modelcontextprotocol.io/)) server so LLM clients can read and modify Pipekit resources on your behalf.

## Prerequisites

* The Pipekit CLI installed (see [Reference > CLI > Install](/reference/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.

## Configuration recipes

The snippets below all assume the `pipekit` binary is on your `PATH`. If it isn't, 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 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.

## Verifying the install

Once your client is connected, ask the agent to call `pipekit_version`. If you get back a Pipekit version string, the server is running and the agent has access.

If `pipekit_version` returns but other tools fail with `401 unauthorized`, your local CLI token isn't on disk. Run `pipekit login`.

## Logging

`pipekit mcp` honors 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 don't interfere with the MCP protocol stream on stdout.

## What's next

* [Tool Inventory](/ai/tool-inventory.md): every tool the server exposes and which are destructive.
* [Security & Transports](/ai/security-and-transports.md): stdio vs HTTP, auth, identity.
* [Troubleshooting](/ai/troubleshooting.md): common failure modes.
* [Patterns](/ai/debug-failed-run.md): worked examples of using AI with Pipekit.