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:

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.

Related MCP server: Cloud Pilot MCP

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

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.