MCP Server & AI Assistant Connectors

---

Tool surface#

It also exposes read-only resources (segops://segments, …/products, …/queries, …/visibility-dashboard) and five starter prompts (audit segments, find visibility gaps, generate a landing page, review competitors, diagnose ingestion).

Authentication & scopes#

Connectors authenticate one of two ways:

• MCP key (mk_) — for Claude Desktop (stdio). Generate one under Settings → API keys → MCP (or via the Connectors page). MCP keys are least-privilege: mcp:read + mcp:write by default, never destructive unless explicitly granted mcp:admin.
• OAuth 2.1 + PKCE — for Claude.ai and ChatGPT (hosted). You sign in to SegOps, pick a tenant, and approve access; the connector receives a short-lived, scoped access token (refreshed automatically).

Scope is enforced per request, by HTTP method: reads need mcp:read, writes need mcp:write, and deletes need mcp:admin — independent of the client.

---

Claude Desktop (stdio)#

1. Connectors → Claude Desktop, click Generate MCP key (owners only).

2. Copy the generated config into claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):

   jsonCopy

   {
     "mcpServers": {
       "segops": {
         "command": "uvx",
         "args": ["segops-mcp"],
         "env": {
           "SEGOPS_MCP_KEY": "mk_…",
           "SEGOPS_API_URL": "https://api.segops.ai/api"
         }
       }
     }
   }

3. Restart Claude Desktop and ask: “List my top 3 segments by member count.”

Requires uv. The server runs locally; only the authenticated API calls leave your machine.

Claude.ai (hosted, OAuth)#

1. Connectors → Claude.ai → Add to Claude.ai, or in Claude.ai add a custom connector with the URL https://mcp.segops.ai/<tenant>/sse.
2. Sign in to SegOps and approve. Done — no key to manage.

ChatGPT (Actions, OAuth)#

1. In the GPT editor → Actions → Import from URL, use https://api.segops.ai/api/mcp/openapi.json.
2. Set Authentication → OAuth: client id chatgpt, scope mcp:read mcp:write, authorization URL https://app.segops.ai/oauth/authorize, token URL https://api.segops.ai/oauth/token.
3. ChatGPT shows a callback URL (https://chatgpt.com/connector/oauth/<id>). Send it to your SegOps admin to add to the chatgpt client's redirect allowlist.

---

Observability & limits#

• Telemetry — every tool call is logged to a tenant-scoped audit trail (GET /api/mcp/tool-calls/): tool name, method/path, status, and duration. We log request shape, never request bodies.
• Rate limit — 100 tool calls / minute / tenant by default (MCP_RATE_LIMIT_PER_MIN), separate from API-key limits; over-limit calls get 429 + Retry-After.

---

Threat model#

What a connected assistant can — and can't — do on your behalf:

• Tenant isolation. A credential is bound to one tenant. Tool calls are scoped to that tenant server-side; the assistant cannot name another tenant.
• Least privilege. MCP keys default to read+write and cannot delete unless granted mcp:admin. Scope is re-checked per request by HTTP method, so a read-only credential is read-only even if the assistant tries to mutate.
• No secret exposure. Secret keys (sk_) are never used by connectors. MCP keys are shown once; OAuth refresh tokens are stored as hashes (non-recoverable) and rotate on every use — a leaked-and-replayed refresh token is detected and the chain is revoked. Authorization codes are single-use and short-lived, and PKCE (S256) is required.
• What the assistant sees. Anything the tools return — segment definitions, user profiles/events, product data, visibility metrics. Treat a connected assistant as having the same read/write reach as the MCP credential you issued. Revoke a key (Settings → API keys) or an OAuth grant (/oauth/revoke) to cut access immediately.
• Prompt-injection awareness. Tool outputs may contain attacker-controlled text (e.g. a user trait). The connector returns data faithfully; your assistant decides what to do with it. Prefer read scopes for analysis workflows, and reserve mcp:write/mcp:admin for trusted, owner-issued credentials.
• Auditability. Every call is in the tool-call audit trail, so you can review exactly what an assistant did and when.

---

Self-hosting the server#

The server is the segops-mcp Python package (sdks/mcp/python). Stdio runs via uvx segops-mcp; the hosted transport (SEGOPS_MCP_TRANSPORT=http) is deployed to Cloud Run (deploy/docker/mcp.Dockerfile, cloudbuild.mcp.yaml) and verifies OAuth access tokens with a shared SEGOPS_MCP_JWT_SECRET. See the package README for all environment variables.