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

Hosted Server

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

Claude Code

claude mcp add --transport http pidgr https://mcp.pidgr.com

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com"
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com"
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "pidgr": {
      "url": "https://mcp.pidgr.com"
    }
  }
}

The hosted server uses OAuth 2.0 for authentication. Your MCP client will prompt you to sign in with your Pidgr account when you first connect.

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 authenticates with a static API key. Create one in the admin dashboard under Settings → API Keys.

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 + API key
Auth	OAuth sign-in via browser	Static API key
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: Sign out and sign back in. Ensure your Pidgr account has the required permissions.
• Local: Verify PIDGR_API_KEY is set and not expired. Check the key hasn’t been revoked in the admin dashboard.

Updating (local)

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