# Pinpole MCP Server

Design cloud architectures, run cost/performance simulations, and **draw them on your
[Pinpole](https://pinpole.cloud) canvas** — from **Cursor**, **Claude Code**, **Codex**,
**Claude.ai**, and **Bolt**.

**Product:** https://pinpole.cloud · **App:** https://app.pinpole.cloud · **Connectors:** [docs/connectors.md](docs/connectors.md)

---

## Quick start (stdio — Cursor, Claude Code, Codex)

### 1. Get a token

Open **Pinpole → Settings → Developer / MCP** and create a personal access token
(`pp_live_…`). Copy it — it's shown only once.

### 2. Configure your agent

**Cursor** — add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pinpole": {
      "command": "npx",
      "args": ["-y", "@pinpole/mcp"],
      "env": {
        "PINPOLE_API_TOKEN": "pp_live_…",
        "PINPOLE_BASE_URL": "https://app.pinpole.cloud"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add pinpole \
  --env PINPOLE_API_TOKEN=pp_live_… \
  --env PINPOLE_BASE_URL=https://app.pinpole.cloud \
  -- npx -y @pinpole/mcp
```

**Codex** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.pinpole]
command = "npx"
args = ["-y", "@pinpole/mcp"]
env = { PINPOLE_API_TOKEN = "pp_live_…", PINPOLE_BASE_URL = "https://app.pinpole.cloud" }
```

---

## Remote connector (Claude Desktop, Claude.ai, Bolt)

| Field | Value |
|-------|-------|
| URL | `https://app.pinpole.cloud/mcp` |
| Transport | HTTP |
| Auth | OAuth (Claude) or API key `pp_live_…` (Bolt) |

**Claude Desktop:** Settings → Connectors → Add custom connector → URL above (leave OAuth Client ID/Secret blank). See [docs/connectors.md](docs/connectors.md).

OAuth discovery: `https://app.pinpole.cloud/.well-known/oauth-authorization-server`

Self-hosted HTTP server:

```bash
npm run build && npm run start:http
```

Env: `MCP_HOST`, `MCP_PORT` (default `3333`), `PINPOLE_BASE_URL`.

Embed in your Node app:

```ts
import { createMcpApp } from "@pinpole/mcp/http";
const app = createMcpApp();
app.listen(3333);
```

---

## Tools

66 MCP tools covering projects, workspaces, AI architect, simulation, deploy, templates,
teams, connectors, billing, and export. Full API parity matrix:
[docs/PARITY.md](docs/PARITY.md).

Highlights:

| Tool | What it does |
|------|--------------|
| `pinpole_build_architecture` | Prompt → architecture → **inline canvas in chat** (+ optional simulation) |
| `pinpole_ai_chat` / `pinpole_ai_vision` | Multi-turn AI architect |
| `pinpole_simulate_cost` | Cost/latency simulation |
| `pinpole_list_projects` / workspace CRUD | Project & canvas management |
| `pinpole_open_canvas` | Inline read-only canvas embed (PAT) + links to full editor |

### Canvas in Cursor

With `PINPOLE_API_TOKEN` set, canvas tools mint a short-lived `/embed/canvas` URL and return
an **inline read-only diagram in chat** (no Pinpole browser login). Use
**Open interactive canvas in Pinpole** for full drag-and-drop editing.

See [docs/connectors.md](docs/connectors.md).
| `pinpole_deploy_execute` / `pinpole_get_drift` | Deploy & drift |
| `pinpole_export_terraform` | Offline Terraform export (no network) |

---

## Environment variables

| Variable | Default | Notes |
|----------|---------|-------|
| `PINPOLE_API_TOKEN` | – | `pp_live_…` from Developer settings |
| `PINPOLE_BASE_URL` | `https://app.pinpole.cloud` | API base URL |
| `PINPOLE_DEV_USER_ID` | – | Local dev only (`ALLOW_DEV_USER_HEADER=1` on server) |

---

## Development

```bash
npm ci
npm run build
npm test
```

```bash
npm test              # smoke: tools/list
npm run test:tools    # list all registered tools
npm run test:parity   # compare tools against docs/PARITY.md
```

Local integration testing (no browser UI): see [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md).

---

## Links

- Pinpole — https://pinpole.cloud
- App — https://app.pinpole.cloud
- Connector setup — [docs/connectors.md](docs/connectors.md)
- Issues — https://github.com/codeforstartups/pinpole-mcp

MIT licensed.