MCP Setup

The Pidgr MCP (Model Context Protocol) server enables AI agents to interact with your Pidgr organization through natural language. It translates MCP tool calls into gRPC RPCs against the Pidgr API.

Overview

• Open source — Apache 2.0 license
• Dual deployment — Run locally on your machine or connect to the hosted server at mcp.pidgr.com
• Dual transport — stdio (for Claude Code, Cursor, Windsurf) and streamable HTTP (for hosted/remote agents)
• 49 tools — Covering campaigns, templates, members, teams, groups, organizations, roles, API keys, heatmaps, and replays

Prerequisites

Create an API key in the admin dashboard under Settings → API Keys. The key has the pidgr_k_ prefix and controls which permissions your agent has.

Hosted Server

The fastest way to get started. Connect directly to mcp.pidgr.com — no binary to download.

Claude Code

claude mcp add --transport http pidgr https://mcp.pidgr.com \
  --header "Authorization: Bearer pidgr_k_your_key"

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com",
      "headers": {
        "Authorization": "Bearer pidgr_k_your_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com",
      "headers": {
        "Authorization": "Bearer pidgr_k_your_key"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com",
      "headers": {
        "Authorization": "Bearer pidgr_k_your_key"
      }
    }
  }
}

Local Server

Run the MCP binary on your machine. Useful for air-gapped environments, custom API endpoints, or development against a local Pidgr API.

Installation

GitHub Releases (recommended)

Download the latest binary for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -LO https://github.com/pidgr/pidgr-mcp/releases/latest/download/pidgr-mcp_darwin_arm64.tar.gz
tar xzf pidgr-mcp_darwin_arm64.tar.gz
chmod +x pidgr-mcp

# Verify checksum
sha256sum -c checksums.txt

# Add to PATH
sudo mv pidgr-mcp /usr/local/bin/

Docker

docker pull ghcr.io/pidgr/pidgr-mcp:latest

From source

git clone https://github.com/pidgr/pidgr-mcp.git
cd pidgr-mcp
go build -o pidgr-mcp ./cmd/pidgr-mcp

Configuration

The local server uses the same API key as the hosted server, passed via environment variable.

Claude Code

claude mcp add pidgr -e PIDGR_API_KEY=pidgr_k_your_key -- pidgr-mcp

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp",
      "env": {
        "PIDGR_API_KEY": "pidgr_k_your_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp",
      "env": {
        "PIDGR_API_KEY": "pidgr_k_your_key"
      }
    }
  }
}

Windsurf

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp",
      "env": {
        "PIDGR_API_KEY": "pidgr_k_your_key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
PIDGR_API_KEY	Yes	API key for authentication
PIDGR_API_URL	No	API endpoint (default: https://api.pidgr.com)

Local Development

Point the MCP server at a local Pidgr API:

PIDGR_API_KEY=pidgr_k_dev_key \
PIDGR_API_URL=http://localhost:50051 \
pidgr-mcp

Hosted vs Local

	Hosted (mcp.pidgr.com)	Local binary
Setup	One command, no install	Download binary
Auth	API key via HTTP header	API key via env var
Transport	Streamable HTTP	stdio
Updates	Automatic	Manual binary update
Custom API URL	No	Yes
Air-gapped	No	Yes
Best for	Most users	Custom environments, local dev

Available Tools

The MCP server exposes 49 tools across 10 service domains:

Domain	Tools	Examples
Campaigns	7	Create, start, list, get, update, cancel, list deliveries
Templates	4	Create, update, get, list
Members	6	Invite, get, list, update role, deactivate, update profile
Teams	8	CRUD, member management
Groups	9	CRUD, member management, user memberships
Organizations	4	Create, get, update, list
Roles	4	List, create, update, delete
API Keys	3	Create, list, revoke
Heatmaps	2	Ingest events, query data
Replays	2	List recordings, get snapshots

Example Usage

Once configured, AI agents can interact with Pidgr naturally:

“Create a campaign called ‘Security Update Q1’ targeting the Engineering group with the security-update template”

“Show me the delivery status for the latest campaign”

“List all members with the Manager role”

“Create a new API key for the CI integration”

Troubleshooting

Connection Refused (local)

Verify PIDGR_API_URL is correct and the API is reachable:

curl -s https://api.pidgr.com/health

Authentication Errors

• Hosted: Verify the Authorization header contains a valid pidgr_k_ key. Check the key hasn’t been revoked or expired in the admin dashboard.
• Local: Verify PIDGR_API_KEY is set and not expired. Check the key hasn’t been revoked in the admin dashboard.
• Permission Denied: The error message indicates which permission is required (e.g., “requires TEAMS_ALL_READ or TEAMS_ALL_WRITE permission”). Add the missing permission to the API key in the admin dashboard.

Updating (local)

Download the latest binary from GitHub Releases and replace the existing binary.