REST Endpoints

Non-GraphQL HTTP endpoints exposed by apps/api — health check, MCP transport, and the Stripe webhook.

Base URL

http://localhost:4000

Endpoints

GET /health

Liveness probe — returns 200 OK with a plain-text body when the server is up.

curl http://localhost:4000/health
# → OK

Used by Docker health checks and load-balancer probes in production.

POST /mcp

The Model Context Protocol endpoint. Accepts and responds with MCP-formatted JSON over the Streamable HTTP transport.

This endpoint is intended for MCP clients (AI agents), not for direct human consumption. See MCP Server for tool documentation and client connection instructions.

# Example: initialise an MCP session (the SDK handles this automatically)
curl -X POST http://localhost:4000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"0.0.1"}}}'

POST /webhooks/stripe

The Stripe webhook intake (plan 07) — the authoritative trigger for platform-subscription state. Stripe (not the browser) is the caller; authenticity is the stripe-signature header, verified against STRIPE_WEBHOOK_SECRET over the raw request body (the server boots with rawBody: true so JSON parsing never corrupts the signature).

• Missing or invalid signature → 400, nothing written.
• Verified subscription/invoice lifecycle events (checkout.session.completed, customer.subscription.updated/deleted, invoice.paid, invoice.payment_failed) → reconciled into platform_subscriptions / platform_invoices, idempotently on Stripe ids — redelivery never duplicates rows.
• Other verified event types → acknowledged with 200 and ignored.
• Reconciliation failures return 5xx so Stripe retries the delivery.
• STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET unset → 503 (the API still boots).

# Local development: forward Stripe test events to the API
stripe listen --forward-to localhost:4000/webhooks/stripe