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)
95 tools — Covering campaigns, templates, audience (teams and groups), users, organizations, roles, API keys, analytics (heatmaps and session replays), and channel integrations

Authentication

The MCP server authenticates with Pidgr over OAuth 2.1 — you sign in through your browser, exactly as you would in the Pidgr apps. There are no keys to paste into config files.

Local (stdio) — on first use the server opens your browser to the Pidgr sign-in page. You sign in (passkey or email one-time code) and approve the requested scopes. The server captures the authorization code on a local loopback listener (authorization code + PKCE, RFC 8252), exchanges it for tokens, and caches them in your OS keychain (with a ~/.config/pidgr/ file fallback). Tokens refresh automatically; if a refresh fails the browser flow runs again.
Hosted (HTTP) — the server runs as an OAuth resource server. Your MCP client discovers where to authenticate via /.well-known/oauth-protected-resource (RFC 9728) and presents a Pidgr bearer token on each request.

The tools your agent can actually use are bounded by both the scopes you approve and your own role: effective permissions are the intersection of the token’s scopes and your role’s permissions. See Authentication for how this works.

Hosted Server

The fastest way to get started. Connect directly to mcp.pidgr.com — no binary to download, no credentials 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"
    }
  }
}

Your MCP client handles the OAuth sign-in the first time it connects.

Local Server

Run the MCP binary on your machine. Useful for custom API endpoints or development against a local Pidgr API.

Installation

GitHub Releases (recommended)

Download the latest binary for your platform from GitHub Releases and verify the checksum:

sha256sum -c checksums.txt

Docker

docker run -e PIDGR_MCP_TRANSPORT=http -p 8080:8080 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

No keys to configure — the first run opens your browser to sign in.

Claude Code

claude mcp add pidgr -- pidgr-mcp

Or add manually to .claude/settings.json:

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp"
    }
  }
}

Windsurf

{
  "mcpServers": {
    "pidgr": {
      "command": "pidgr-mcp"
    }
  }
}

Environment Variables

Variable	Required	Default	Description
`PIDGR_MCP_TRANSPORT`	No	`stdio`	`stdio` or `http`
`PIDGR_API_URL`	No	`https://api.pidgr.com`	API endpoint (gRPC base URL)
`PIDGR_INTEGRATIONS_URL`	No	`PIDGR_API_URL`	IntegrationsService endpoint. Falls back to `PIDGR_API_URL` when unset.
`PIDGR_MCP_ADDR`	No	`:8080`	Listen address (http mode)
`PIDGR_OAUTH_ISSUER`	No	`https://auth.pidgr.com`	OAuth issuer URL. Authorize and token endpoints are discovered from `{issuer}/.well-known/oauth-authorization-server`.
`PIDGR_OAUTH_CLIENT_ID`	No	`pidgr-mcp`	OAuth client id
`PIDGR_OAUTH_SCOPE`	No	the Pidgr scope set	Space-separated scopes requested at authorization
`PIDGR_MCP_RESOURCE_URL`	No	`https://mcp.pidgr.com`	Resource identifier advertised in protected-resource metadata (http mode)

Local Development

Point the MCP server at a local Pidgr API:

PIDGR_API_URL=http://localhost:50051 pidgr-mcp

Hosted vs Local

	Hosted (`mcp.pidgr.com`)	Local binary
Setup	One config entry, no install	Download binary
Auth	OAuth via your MCP client	OAuth via browser sign-in on first run
Transport	Streamable HTTP	stdio
Updates	Automatic	Manual binary update
Custom API URL	No	Yes
Best for	Most users	Custom environments, local dev

Capabilities

The MCP server exposes 95 tools across these domains:

Domain	Examples
Campaigns	Create, update, start, cancel, list; per-user delivery status; post-campaign archetype breakdowns
Templates	Versioned templates with variable substitution; Markdown, Rich, and HTML content types; translations
Audience	Manage groups and teams, add/remove members, query memberships in batch
Users	Invite users, manage profiles, assign roles, deactivate accounts
Organizations	Organization settings, default workflows, SSO attribute mappings
Roles & Permissions	Create custom roles with granular permission sets
API Keys	Create scoped keys with optional expiration, list, revoke
Analytics	Touch heatmap queries, session recordings, snapshot playback data
Integrations	Per-channel recipient reachability and per-channel cost-cap policies

Reachability identifiers (email addresses, phone numbers, chat user ids) are treated as sensitive: they are encrypted server-side, never logged, and never returned over the wire.

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

Browser flow doesn’t complete (local)

The stdio server needs to open a browser and receive the redirect on a local loopback port. Make sure you complete the sign-in and consent screens in the browser tab it opens; if the flow expired, retry the tool call and a fresh browser flow starts.

Connection refused (local)

Verify PIDGR_API_URL is correct and the API is reachable.

Permission denied

The error message names the missing permission. Two things bound what your agent can do:

Scopes — the scopes approved at sign-in (override with PIDGR_OAUTH_SCOPE and re-authenticate to change them).
Your role — a token can never exceed the permissions of the user who approved it.

If a tool fails with a permission error, check both that the relevant scope was granted and that your Pidgr role includes the named permission.

Updating (local)

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