Build on Cultcha with AI or code

1. Connect an AI assistant. Add this server URL as a custom connector. There’s no key to copy: your assistant opens Cultcha, you sign in and approve it.
   Server URL

   https://cultcha.app/api/mcp

2. Ask it something. “How many active members do we have, and how many joined this month?”
3. Or call the API from a script with a personal token, made on the Developers page once you’re signed in.

Clients configured in a file or a terminal:

claude mcp add --transport http cultcha https://cultcha.app/api/mcp

{
  "mcpServers": {
    "cultcha": {
      "url": "https://cultcha.app/api/mcp"
    }
  }
}

{
  "servers": {
    "cultcha": {
      "type": "http",
      "url": "https://cultcha.app/api/mcp"
    }
  }
}

Each one asks you to sign in the first time it connects (in Claude Code, run /mcp and choose Authenticate). Clients that can only send a fixed key, such as Copilot Studio with OAuth tools turned off, can send a personal token as an X-API-Key header instead.

AI apps: OAuth 2.1

• Authorization code flow with PKCE (S256 only). No implicit or password grants.
• Clients register themselves through dynamic client registration; public clients need no secret.
• An unauthenticated MCP request gets 401 with a WWW-Authenticate header naming the protected-resource metadata, so clients find the sign-in on their own.
• Access tokens (cultcha_at_…) last 24 hours. Refresh tokens (cultcha_rt_…) last 30 days from their last use and rotate on every refresh. Reusing an old refresh token ends the connection, since it means someone else has a copy.

Scripts: personal tokens

• Made on the Developers page by a manager or admin, shown once, and stored only as a hash. Format: cultcha_pat_….
• Send it as Authorization: Bearer cultcha_pat_…. The same token works for the REST API and the MCP server.
• Keep it in an environment variable or a secret manager, never in code or a shared document.

Scopes and permissions

Every connection acts as the person who made it: one business, their role’s access, nothing more. No token can issue refunds, manage staff, or create further tokens. Removing the person, or revoking the connection on the Developers page, stops it at once.

Tools carry MCP annotations: every tool but request is marked read-only, and request is marked destructive, so clients ask before it runs. Assistants are told to confirm any change with you first.

curl -s https://cultcha.app/api/mcp \
  -H "Authorization: Bearer $CULTCHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_report","arguments":{"report":"memberships"}}}'

Base URL https://cultcha.app. JSON in and out. Money is in dollars, not cents; dates are ISO 8601 in UTC. List endpoints take page and limit. The full contract is the OpenAPI 3.1 spec, which imports into Postman, Insomnia or a ChatGPT action.

curl -s "https://cultcha.app/api/memberships?status=active" \
  -H "Authorization: Bearer $CULTCHA_TOKEN"

const res = await fetch('https://cultcha.app/api/memberships?status=active', {
  headers: { Authorization: `Bearer ${process.env.CULTCHA_TOKEN}` },
})
if (!res.ok) throw new Error((await res.json()).error)
const memberships = await res.json()

import os, requests

res = requests.get(
    "https://cultcha.app/api/memberships",
    params={"status": "active"},
    headers={"Authorization": f"Bearer {os.environ['CULTCHA_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
memberships = res.json()

Signed in, the list_endpoints tool searches every endpoint the person can call, several hundred in all, including the ones not listed here.

MongoDB collections, each row scoped to one business. The primary key is always _id, and relationships are ObjectId references. Signed in, the get_schema tool returns every field, and query runs find, count or aggregate on them, limited to what the person can see.

Customer

A guest / member. The person who books, buys and checks in.

Membership

A recurring plan held by a customer: status, price, billing cadence, arrears.

Transaction

A sale, refund or invoice. cart holds the line items.

Product

Anything sellable, told apart by type: shop, class, course, membership, prepaid, package, general, gift_card.

Schedule

One class/course session at a time and place, with its attendees.

Checkin

One attendance record — a guest admitted to a session or on a pass.

CustomerPass

A guest's own pass bought from a PrepaidPack, with its remaining balance.

PrepaidPack

A pack of visits or items sold up front (the product a CustomerPass comes from).

GiftCard

A gift card or promo/checkout link, told apart by kind.

Location

A venue (site). Products, sessions and devices belong to one.

Employee

A staff member, with a role: STAFF, FINANCE, MANAGER, ADMIN.

Segment

A saved, rule-driven group of guests. Rules are re-evaluated live.

Campaign

A marketing message sent by email or push to an audience.

Form

A staff-built form (waiver extras, intake questions).

FormResponse

One completed form, answered by a guest.

• Errors are JSON: { "error": "…" } with a standard status code.
• 400: The request didn’t validate; the message says why.
• 401: Missing, expired or revoked token. Sign in again or use a current token.
• 403: The token’s owner can’t do this, or the token is read-only.
• 404: No such record in this business.
• MCP errors follow JSON-RPC 2.0, with an error object in place of result.

Use the API at a pace a person would. Need bulk access or higher volumes? Talk to us first.

For client builders: everything an MCP or OAuth client needs to configure itself.

• Protected resource metadata (RFC 9728)/.well-known/oauth-protected-resource/api/mcp
• Authorization server metadata (RFC 8414)/.well-known/oauth-authorization-server
• Dynamic client registration (RFC 7591, POST)/api/oauth/register
• Authorization endpoint/oauth/authorize
• Token endpoint (POST)/api/oauth/token
• Revocation endpoint (RFC 7009, POST)/api/oauth/revoke
• OpenAPI 3.1 spec/api/openapi.json
• These docs as Markdown/docs.md
• Summary for AI tools/llms.txt
• Full text for AI tools/llms-full.txt