susMCP

Suspicious Antwerp's company-wide conversational data layer: a standalone MCP server that wraps existing systems (adsAgent, suspiciousAI, Shopify MCP) behind one OAuth-authenticated connector, so the CEO + ops manager can ask Claude (web / Desktop / Slack) about company data.

Full design, decisions, and the 11 implementation slices live in the plan: ~/.claude/plans/twinkling-mapping-coral.md.

Status

Slice 1 (walking skeleton) — in progress. OAuth resource server (WorkOS AuthKit) + one CS tool (cs_get_ticket_messages, proxying suspiciousAI's already -exposed endpoint) + central tool_invocations tracing, brought up by one compose command.

Architecture (v1)

Claude (web/Desktop/Slack)  --OAuth 2.1/PKCE (WorkOS)-->  susMCP (this server)
                                                            |  own Postgres:
                                                            |   - tool_invocations
                                                            |   - synced query data (later)
      curated tools (live, HTTPS + per-domain service cred) |
        +--> suspiciousAI  (/api/tickets, /api/lookup*, /api/analytics)
        +--> adsAgent      (/api/metrics, /api/ads, ...)          [slice 5+]
        +--> Shopify MCP   (read-only, mutations gated)           [slice 6]
      escape hatch: susmcp_query = read-only SQL over the synced DB  [slice 8]

Curated tools proxy live for freshness; the escape hatch queries susMCP's own synced copy. All mechanics (httpx call, error taxonomy, tracing) live in ONE proxy factory (proxy.py); tool bodies are one line each.

Local dev

cp .env.example .env          # dev defaults work; leave WORKOS_AUTHKIT_DOMAIN empty
docker compose up --build     # brings up susmcp + Postgres (HTTP, no TLS, no auth)

Auth is DISABLED when WORKOS_AUTHKIT_DOMAIN is empty — dev only, never ship it.

Tests

pip install -e ".[dev]"
pytest

Tests run without a database (tracing writes are best-effort and patched in tests).

Production / connecting to Claude — HITL setup

These steps need real accounts/infra and are done by a human (see the plan's Phase 0 + Issue 1):

1. WorkOS AuthKit: create the project, add the exec accounts, enable Google sign-in, set WORKOS_AUTHKIT_DOMAIN and BASE_URL (the server's public https URL).
2. Host + TLS: deploy on susMCP's own host; the prod compose overlay (docker-compose.prod.yml, added with the deploy slice) runs nginx + certbot for Let's Encrypt. docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build.
3. suspiciousAI service credential: set CS_BASE_URL + CS_API_KEY (its INTERNAL_API_KEY).
4. Register the connector in claude.ai (Enterprise admin) pointing at the server's /mcp URL; approve the OAuth flow.
5. Verify: ask about a ticket → cs_get_ticket_messages fires (visible in the transcript) → a tool_invocations row is written with the exec's identity.

Accepted risks (v1, deliberate — see plan)

• tool_invocations captures full args (incl. customer PII) unbounded/plaintext, no retention/redaction. GDPR-relevant; revisit before wider rollout.
• susMCP is a single point of failure; restart+healthcheck only, no external uptime monitor yet.