MalGomo MCP Server v1.2.0

A remote Model Context Protocol server. It exposes the MalGomo agency dashboard (revenue KPIs, fan growth, earnings) as tools for an AI agent. It is a thin, read-only wrapper over the backend REST at https://api.malgomo.com — all authentication, agency scoping and the owner/admin gate live in the backend; this server only carries your token.

1. Endpoints

When OAuth is enabled (PUBLIC_URL set), the server also serves the standard OAuth endpoints — /authorize (sign-in page), /oauth/login, /token, /register (Dynamic Client Registration), /revoke — plus discovery metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Your MCP client uses these automatically; you do not call them by hand.

2. Logging in

Authentication uses your normal MalGomo CRM email + password. There are two modes:

A) OAuth at connect (recommended, when the server has PUBLIC_URL set). When you add the connector, the client discovers the login and opens a sign-in page in your browser. You log in once; the client stores the token and refreshes it automatically — no per-chat login. The /mcp endpoint requires a valid bearer token in this mode.

B) In-chat tool (when OAuth is off). Session-based — log in once per connection via the malgomo_login tool, then every data tool works without re-auth:

1. Connect your MCP client to POST /mcp (it performs the MCP initialize handshake and gets a session id).
2. Call the malgomo_login tool with your MalGomo email and password.
3. The server exchanges them with Supabase (https://xgifdbzqplddpeobtwtw.supabase.co) for a short-lived token, stores it for this session only, and probes whether your account may read dashboard data.
4. Call malgomo_get_kpis / malgomo_get_fans / malgomo_get_earnings.

The token auto-refreshes on expiry while the connection is open. Credentials are used once and never stored — only the resulting token lives in memory for the session. Disconnecting (or malgomo_logout) clears it.

Access level: dashboard data is owner/admin only. A member account can log in but will get forbidden on the data tools.

3. Tools

malgomo_login (write — auth)

Log in with email + password. Verifies once per session.

malgomo_session_status (read)

Reports whether the connection is logged in, as whom, and the token expiry. No arguments.

malgomo_logout (write)

Clears the session token from this connection. No arguments.

malgomo_get_kpis (read)

Agency-wide net payout revenue for the chosen period.

Returns: hero_net_eur, currency, mobile_period, kpi_period, revenue_by_category_eur, hourly_revenue_current, daily_revenue_current, creator_count, per_creator[], latest_fetched_at.

malgomo_get_fans (read)

Fan growth across the agency.

Returns: period, totals {free, sub, total}, new_today_total, new_in_period {free, sub, total}, daily_new[] {at, new_free, new_sub}, per_creator[] {profile_name, free, sub, total, new_today}, generated_at.

malgomo_get_earnings (read)

Earnings from the payout database.

Returns: period, currency, period_totals {gross, net}, month {gross, net, fee}, daily[] {at, gross, net}, transactions[] {kind, title, fan, net, gross, at, profile_name}, per_creator[] {profile_name, gross, net}, generated_at.

period argument (all three data tools)

4. Connecting a client

Add this server as a remote/custom MCP connector pointed at POST /mcp. With OAuth on (mode A), the client shows a sign-in page at connect time — log in there and you are done. With OAuth off (mode B), no header is required and you authenticate with the malgomo_login tool. (Advanced: send Authorization: Bearer <supabase-jwt> on the connection to skip the login tool.)

Quick raw check with curl (initialize handshake):

curl -i -X POST <this-url>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"curl","version":"0"}}}'

The response carries an mcp-session-id header — send it back on later requests.

5. Security & scoping

• The agency is derived from your verified token in the backend, never from a client parameter — cross-agency reads are impossible.
• Owner/admin only. Members get forbidden.
• No financial PII (IBAN/payout accounts) is exposed; the backend contract carries none.
• Sessions are in-memory and isolated per connection. A login in one connection never affects another.
• This server stores no credentials and writes nothing — every data tool is read-only.
• OAuth (mode A): authorization codes are one-time + short-lived; access/refresh tokens are random and map server-side to your Supabase session (PKCE enforced). The login password is entered only on the sign-in page, never in chat.
• Your Supabase token never leaves the server — an MCP client only ever holds an opaque MalGomo token that maps to it internally.
• The sign-in endpoint is rate-limited and rejects cross-origin POSTs; the OAuth code/token/client stores are bounded + TTL'd.
• The mcp-session-id is a connection secret (it rides your logged-in token). It is a random UUID sent only over TLS — treat it like a bearer token; do not share it.
• Sessions are capacity-bounded and idle-reaped to bound memory + token retention.

6. Server configuration (env)

Note: sessions live in process memory, so run a single instance (or add shared session storage before scaling out).