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 is present and actually authenticates against that region.
3. The workspace's tier supports the Public API — a Free-tier workspace gets a clear "requires Team or Business tier" message, not a raw 403.

Modes

SEGMENT_MCP_MODE = read (default) | write | admin

• read — every tool above. No mutation reachable, at any mode.
• write — would add Tier 3 replace-semantics changes (none shipped yet), each echoed back for confirmation before executing.
• admin — would add Tier 2 deletes (none shipped yet), gated behind a typed confirmation naming the exact resource — not just confirm=true.

See src/segment_mcp/modes.py for the full tier model and docs/what-this-refuses-to-do.md for what stays out of scope regardless of mode.

Profile API — a separate, higher trust tier

The Profile API returns PII on named individuals — traits, external IDs, event history, and identity links for a specific person. This is the most privacy-sensitive read anywhere in this server's surface, so it is walled off from everything else:

• A separate credential, SEGMENT_PROFILE_TOKEN — never the main SEGMENT_API_TOKEN. Also requires SEGMENT_PROFILE_SPACE_ID (your Unify Space ID, not your workspace ID).
• Explicit opt-in. If SEGMENT_PROFILE_TOKEN is unset, no profile tool is registered — the capability doesn't exist for that server instance.
• Every lookup is logged — collection, id_type, and the caller — before the request is even sent, via client/profile_api.py's segment_mcp.profile_api logger. The log records that a lookup happened and which profile, as a truncated SHA-256 digest of the lookup key, never the raw identifier — this client never logs the raw identifier itself, and it silences httpx's own request-URL log process-wide at construction so the identifier doesn't leak that way either, since the Profile API puts it in the URL path. The digest cannot be reversed back to the identifier, but repeated lookups of the same profile are still correlatable across log lines for auditing.
• Lookups are case-sensitive. The wrong case returns an empty result, not an error — this client lowercases every lookup value at its boundary and logs a warning when it had to.

No profile-lookup MCP tool is wired into server.py yet — this is the client and trust-boundary machinery a future tool will be built on, per BUILD-PLAN.md's v0.2 scope.

Development

uv sync
uv run pre-commit install
uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest

See CONTRIBUTING.md and AGENTS.md.

See also

Every project here shares one idea: a GTM system should refuse to act on data it cannot verify.

campaign-preflight — the same refusal to coerce missing evidence into a pass. insufficient_data is its own state in both.

pipeline-waterfall — downstream of this. Reconciles the bookings and pipeline waterfall, and fails the build rather than reporting a bridge that does not tie out.

License

MIT — see LICENSE.