Skip to main content

​
MCP Overview

The Subscriptions Engine ships with a companion MCP (Model Context Protocol) server at https://mcp.oluwadunsin.dev/mcp. It lets any MCP-aware client — Claude Desktop, Claude web, Cursor, Codex, ChatGPT connectors — call the engine’s REST API through structured tools instead of hand-crafted HTTP requests. The server is a thin translation layer. Every tool call is forwarded to the existing REST API using the merchant’s X-Api-Key, so tenant isolation, validation, and every downstream side effect (webhooks, emails, DB writes) continue to run through the same middleware and services that back the public API.

​
What you get

CategoryCountPurpose
Tools15Query, analyze, act, or generate reports on subscription data.
Resources4 static + 1 templateRead-only URIs the client can browse (plans://all, customers://{emailOrCode}, …).
Prompts2Reusable multi-step workflows (monthly_business_review, subscription_health_check).

​
Design

  • Transport: Streamable HTTP. Works over standard HTTPS to any hosted MCP client.
  • Endpoint: https://mcp.oluwadunsin.dev/mcp.
  • Auth: the MCP client sends X-Api-Key: <your merchant key>. The server relays that header to the engine unchanged. Requests without a key are rejected at the HTTP layer with 401 unauthorized before any tool logic runs.
  • Rate limit: per API key, token-bucket, 120 requests / minute by default. Exceeded budgets return 429 with Retry-After.
  • Errors: tool failures are returned as a structured envelope { code, message, retryable } so clients can distinguish invalid_input (never retry) from engine_error (safe to retry).
  • Health: GET https://mcp.oluwadunsin.dev/health bypasses auth and is intended for load-balancer probes.

​
When to use the MCP vs the REST API

  • REST API — programmatic integrations, merchant backends, automated systems.
  • MCP server — AI agents, dashboards driven by natural language, one-off ops questions (“what’s my MRR”, “retry failed invoices from yesterday”, “why did churn go up”).
Both talk to the same tenant data with the same API key. Pick whichever fits the caller.

​
Next steps