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