apex-mcp-server
A read-only Model Context Protocol server for the Apex Rides API, deployed as a Cloudflare Worker. It authenticates against AWS Cognito with a service account and exposes four read-only tools over MCP's Streamable HTTP transport.
Tools
| Tool | Description | | --- | --- | | popular_classes | Top popular workouts by session count in a date range. | | search_classes | Search workouts with filters (paginated). | | get_class | Detailed info for a single on-demand class. | | list_instructors | List all instructors (including archived). |
All tools are GET-based. There are no write operations and no generic passthrough.
Setup & Deploy
1. Install
npm install2. Set secrets
npx wrangler secret put APEX_SERVICE_PASSWORD # the Cognito service user password
npx wrangler secret put MCP_SHARED_SECRET # a strong random stringFor local development, create a .dev.vars file (git-ignored) with the same keys:
APEX_SERVICE_PASSWORD=...
MCP_SHARED_SECRET=...3. Deploy
npx wrangler deployUsage
Connect an MCP client to the worker's MCP endpoint, with the shared secret as the first path segment:
https://<worker>.workers.dev/<MCP_SHARED_SECRET>/mcpAny request whose first path segment is missing or does not match MCP_SHARED_SECRET gets a 401.
The transport is MCP Streamable HTTP (a single endpoint handles both the GET stream and POST messages). The legacy Node-only SSE transport does not run on Cloudflare Workers, so it is not used here.
Notes & Guardrails
- No client secret.
SECRET_HASHis omitted entirely since the Cognito app
client has no secret.
- Token caching. The access token is cached in module scope and refreshed via
REFRESH_TOKEN_AUTH when near expiry.
- Date validation.
popular_classesvalidatesfrom/toagainstYYYY-MM-DD
and appends T23:59:59Z to include the full final day.
- Name search. Since the Apex API has no text search,
search_classesfetches
up to 500 results and filters client-side when name is provided.
- Read-only enforcement. Only the four
GET-based tools above are implemented.
