Pinpole MCP Server

Design cloud architectures, run cost/performance simulations, and draw them on your Pinpole canvas — directly from Claude Code, Cursor, and OpenAI Codex. A draw.io replacement driven by your AI agent.

Product: https://pinpole.cloud · App: https://app.pinpole.cloud

---

What it does

Your coding agent can now talk to Pinpole over the Model Context Protocol:

Tool	What it does	Auth
pinpole_build_architecture	Flagship. Prompt → validated architecture → drawn on your canvas. Returns a canvas URL. Optional cost simulation.	token
pinpole_create_architecture	Generate a {nodes, edges} graph from a prompt (no drawing).	token
pinpole_simulate_cost	Run the simulation engine over a graph at a traffic level → per-node + total monthly cost, latency p50/p95/p99, throttling alerts.	none
pinpole_draw_on_canvas	Persist a graph to your canvas (creates project/workspace if needed). Auto-layout.	token
pinpole_open_canvas	Get the canvas deep link for a project/workspace.	none
pinpole_list_projects / pinpole_create_project	Manage projects.	token
pinpole_export_terraform	Generate Terraform from a graph (offline).	none
pinpole_list_services	List AWS service ids the canvas understands (local repo only).	none

A typical flow: the agent calls pinpole_build_architecture with a description, Pinpole's AWS Well-Architected model designs it, the nodes + connections appear on your canvas, and the agent hands you a URL to open the live, editable diagram.

---

1. Get a token

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

Tokens act on behalf of your account (create projects/workspaces, draw on the canvas, use AI-architect credits). Revoke any token from the same screen.

2. Configure your agent

Claude Code

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

Or commit .mcp.json to a repo (see examples/claude-code.mcp.json).

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project) — see examples/cursor.mcp.json:

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

OpenAI Codex

Add to ~/.codex/config.toml — see examples/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" }

---

Environment variables

Variable	Default	Notes
PINPOLE_API_TOKEN	–	Personal access token (pp_live_…). Sent as Authorization: Bearer.
PINPOLE_BASE_URL	https://app.pinpole.cloud	Point at a local server for testing.
PINPOLE_DEV_USER_ID	–	Local dev only. Sent as x-pinpole-dev-userid (requires the server to run with ALLOW_DEV_USER_HEADER=1). Lets you test without a token.

---

Local development & testing

From the Pinpole repo:

npm run mcp:build           # compile mcp/ → mcp/dist
ALLOW_DEV_USER_HEADER=1 npm run dev   # start the app (default :3031 via `npm start`, :3000 via dev)

Then point your agent at the local build with the dev header — see examples/local-dev.mcp.json. PINPOLE_DEV_USER_ID is your Firebase uid.

Smoke-test the tool list without an agent:

printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
 | node mcp/dist/server.js

Or use the inspector: npx @modelcontextprotocol/inspector node mcp/dist/server.js.

HTTP / remote connector mode

npm run mcp:http serves a Streamable-HTTP endpoint at POST /mcp (with the minimal OAuth scaffolding Claude's custom-connector probe expects). Env: MCP_HOST, MCP_PORT (default 3333).

---

Links

• Pinpole — https://pinpole.cloud
• App — https://app.pinpole.cloud
• Issues & source — https://github.com/codeforstartups/pinpole-mcp

MIT licensed.