Pinpole Server

Design cloud architectures, run cost/performance simulations, and draw them on your Pinpole canvas — from Cursor, Claude Code, Codex, Claude.ai, and Bolt.

Product: https://pinpole.cloud · App: https://app.pinpole.cloud · Connectors: 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:

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

Claude Code:

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:

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

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

Self-hosted HTTP server:

npm run build && npm run start:http

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

Embed in your Node app:

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.

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

npm ci
npm run build
npm test

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.

---

Links

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

MIT licensed.