segment-mcp

A read-first MCP server for Twilio Segment. Answers which destinations get which events, which sources are dead, and which are governed by nothing — the questions nobody can answer without clicking through forty screens.

Read-only by default

SEGMENT_MCP_MODE defaults to read, and every tool this server ships today is a read. Shipping with zero write tools is a feature, not a limitation — see BUILD-PLAN.md §2. write and admin modes exist in the tier model (src/segment_mcp/modes.py) for when gated writes land; right now there is nothing for them to unlock.

What this refuses to do — permanently, not "for now"

POST /regulations and POST /regulations/sources/{id} — workspace-scoped, irreversible deletion or suppression of user data across every source — are unreachable in every mode, with no configuration path to enable them. Three independent things enforce this: the mode-authorization layer refuses it before even checking the current mode, the API client refuses to send the request before it reaches the network, and no tool this server registers references it in any form.

This isn't a gate waiting for the right permission level. It's a line, because these endpoints accept an array of subjects and one malformed or hallucinated call can permanently delete thousands of profiles with no undo. Full reasoning: docs/what-this-refuses-to-do.md.

Quick start

Requires a Segment workspace on Team or Business tier and a Public API token (see Prerequisites below).

gh repo clone katekruger/segment-mcp
cd segment-mcp
uv sync
cp .env.example .env      # fill in SEGMENT_API_TOKEN and SEGMENT_REGION
uv run segment-mcp

Point an MCP client (Claude Desktop, Claude Code, etc.) at it over stdio. The server refuses to start — loudly, with a clear message — if the token, region, or workspace tier isn't right; see Startup checks.

The five tools

Each composes several Public API calls into one structured answer, not a raw endpoint dump:

Prerequisites

• Team or Business tier. The Public API is not available on Free or Add-on plans. There is no workaround, and the server's startup checks fail with a clear message rather than a raw 403 if your workspace doesn't qualify.
• A Public API token. Only a Workspace Owner can mint one: Segment App → Workspace Settings → Access Management → Tokens → Create Token → Public API (not Config API).

Region configuration

SEGMENT_REGION=us   # or eu

There is no default — you must set this explicitly. An EU workspace whose API calls are pointed at the US endpoint doesn't error; it just silently returns nothing, which is a far worse failure mode than a crash. This server's startup checks call the API once with your configured region and fail loudly if the token doesn't actually belong to it, naming the region that does.

Startup checks

All fatal — the server refuses to start rather than fail confusingly on the first tool call:

1. SEGMENT_REGION is set and one of us/eu.
2. `SEGMENT_API_TOKEN

... View full README on GitHub