FavCRM MCP
Install snippets, examples, and docs for the FavCRM Model Context Protocol server. The server itself is hosted at https://api.favcrm.io/mcp — this repo is for client setup and community examples.
194 typed tools — customers, bookings, loyalty, invoices, payments, WhatsApp / SMS / email — exposed via MCP. Works with any agentic client that speaks Streamable HTTP transport.
🤖 AI Agent Skills
Building against the FavCRM headless backend with an AI Agent? Teach your AI our best practices, standard operating procedures, and MCP tool shapes by installing our official skills:
# Example: Install the Booking Operator skill
npx skills add https://github.com/favcrm/mcp/tree/main/skills/favcrm-booking-operator
# Or install all skills at once
npx skills add favcrm/mcp
See the skills/ directory for the full list of available agent skills.
Public agent skills live in skills/: portable workflow packages for agentic registration, team onboarding, channel setup, booking operations, customer lifecycle, comms approval, billing/commerce, content, sales ops, knowledge training, and reporting. They are source-readable for agents and marketing, while FavCRM runtimes install vetted versions through the platform skill registry.
| Client | Status | Setup |
|---|
| Vercel v0 | ✅ Live | Marketplace install — auto-provisions a workspace + injects env vars |
| Cursor | ✅ Live | mcp.json snippet |
| Smithery | ✅ Live | smithery mcp add favcrm/favcrm |
| Claude Desktop / Connector | 🚧 Pending | OAuth provider (Phase 3, ~3 weeks) |
| ChatGPT Apps Directory | 🚧 Pending | Listing under review |
| Windsurf / Continue.dev / Zed | ✅ Works | Same mcp.json shape as Cursor |
Get a key
Two ways:
Option A — your agent signs you up (no form, no portal click)
Connect FavCRM to your client first (see Cursor section below) using a placeholder env var. Then ask your agent:
"Sign me up for FavCRM. Yoga studio called Stretch + Breathe in Hong Kong."
The agent will:
- Call
register_organisation_request — server emails a 6-digit code to you
- You paste the code back in chat
- Agent calls
register_organisation_verify — server returns a fresh fav_mcp_* key
- Agent stores the key and starts working immediately
See skills/favcrm-agentic-registration for the portable SKILL.md workflow.
Behind the scenes: 10-min OTP, real email-ownership check, per-IP rate limit (3/hour, 20/day). No phishing surface, no fake demos.
Option B — sign up the traditional way
favcrm.io/signup → portal → Settings → MCP Keys → copy the fav_mcp_* value.
Existing FavCRM merchants: same place, no plan upgrade needed for MCP access.
Free tier (both options): 100 customers, 200 bookings/month, 1k MCP calls/month, 30-day trial of higher limits.
Bootstrap from the CLI
The favcrm CLI can also run the zero-state flow:
favcrm signup request --email owner@example.com --organisation-name "Ada Studio"
favcrm signup verify --request-id <request-id> --code <code>
favcrm doctor
favcrm team invite create --email teammate@example.com --role staff
favcrm whatsapp status
favcrm whatsapp connect --mode cloud-api
Team invitees can accept without an existing API key:
favcrm team invite accept-request --token <invite-token>
favcrm team invite accept-verify --token <invite-token> --code <code>
Cursor
Verified shape, cursor.com/docs/mcp.
~/.cursor/mcp.json (or .cursor/mcp.json in your project):
{
"mcpServers": {
"favcrm": {
"url": "https://api.favcrm.io/mcp",
"headers": {
"Authorization": "Bearer ${env:FAVCRM_API_KEY}"
}
}
}
}
Then export the key — anywhere your Cursor process reads env vars:
# shell rc
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> ~/.zshrc
# or per-project (direnv)
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> .envrc
Restart Cursor → Settings → MCP → favcrm connects → 194 tools land in chat.
Why ${env:VAR} instead of inline? Cursor interpolates env vars at request time so the key never lands in your repo or shared config.
Smithery
favcrm.io on Smithery — install via CLI:
npm i -g @smithery/cli
smithery login
smithery mcp add favcrm/favcrm
For a project-scoped install, smithery mcp add favcrm/favcrm --client cursor writes the right mcp.json block.
Claude Desktop
🚧 OAuth-based connector pending Phase 3. Once live:
claude.com → Connectors → Add custom connector- URL:
https://api.favcrm.io/mcp
- Authorize via OAuth → workspace selector → tool list
Until then, advanced users can wire FavCRM into Claude Desktop's claude_desktop_config.json via the same Bearer-header pattern as Cursor (community-only path; not currently in Anthropic's connector directory).
ChatGPT
🚧 Apps Directory listing under review. Once approved:
- ChatGPT → Tools menu → Apps → search "FavCRM"
- Add → OAuth handshake → workspace selector
- 26 curated tools land in chat (read-mostly + safe writes; destructive ops gated behind confirmation)
Test it
Once your config is live, ChatGPT/Cursor/Claude will list tools automatically. To smoke-test from the command line:
# Discovery (no auth needed — public-scan endpoint)
curl https://api.favcrm.io/.well-known/mcp/server-card.json | jq '.tools | length'
# → 194
# Auth + initialize
curl -s https://api.favcrm.io/mcp \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $FAVCRM_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
| jq
# Call a read-only tool
curl -s https://api.favcrm.io/mcp \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $FAVCRM_API_KEY" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_membership_tiers","arguments":{}}}' \
| jq
See examples/ for more.
Tool surface
194 tools across 24 scopes. Every tool ships with annotations:
title — human-readable labelreadOnlyHint — true for list_* / get_* / search_* / etc.destructiveHint — true for delete_* / cancel_* / void_* / refund_*openWorldHint — true for tools that hit external services (WhatsApp, Stripe, email)idempotentHint — true for set_* / update_* / upsert_* and read-only
Clients can use these to gate destructive calls or estimate cost. The full catalog at https://api.favcrm.io/.well-known/mcp/server-card.json is the source of truth — listings here are summaries only.
Agents should use query_favcrm_platform before guessing tool names or argument shapes. For merchant-specific facts, policies, pricing notes, FAQs, or brand guidance, use query_company_knowledge; it returns snippets with source document IDs rather than full documents.
| Scope | Sample tools | Read-only | Write |
|---|
contacts | search_members, get_member_profile, create_account, attach_tags | 5 | 6 |
bookings | list_services, get_available_slots, create_booking | 12 | 15 |
membership | list_tiers, enrol_membership, earn_loyalty_points | 4 | 3 |
shop | list_products, get_order, create_order | 8 | 6 |
invoices | list_invoices, mark_invoice_paid | 4 | 4 |
campaigns | list_campaigns, send_campaign (gated) | 5 | 3 |
blog | list_posts, publish_post | 14 | 13 |
Agent Issue Reports
Agents should call report_agent_issue when an MCP-native path is missing, a tool schema is confusing, a tool fails unexpectedly, or they had to fall back to REST/SDK behavior. Include expected behavior, actual behavior, steps tried, relevant tool calls/logs, AI analysis, and clarification questions. FavCRM routes these reports to the platform support queue for triage.
Example:
favcrm tool call report_agent_issue '{"title":"Missing account creation MCP tool","severity":"high","area":"mcp_tool_missing","expectedBehavior":"Agent can create an account via MCP only.","actualBehavior":"Agent had to use SDK fallback.","stepsTried":["Listed tools","Tried create_contact"],"aiAnalysis":"Account creation exists in backend services but was not exposed in MCP."}'
Plan operations
Agents can inspect and preflight plan access without leaving MCP:
favcrm tool call get_plan_status '{}'
favcrm tool call check_plan_operation '{"toolName":"create_account"}'
favcrm tool call list_plan_options '{}'
favcrm tool call create_plan_upgrade_link '{"planCode":"favcrm-lite","billingCycle":"monthly","confirm":true}'
Use check_plan_operation before writes that may hit module, scope, subscription, or quota gates. If the result includes upgradeAction, show the user the returned action. Stripe links are only created by create_plan_upgrade_link with confirm=true.
Auth modes
| Token kind | Lifetime | Use case |
|---|
fav_mcp_* API key | Long-lived, revocable | Cursor, Windsurf, Zed, Continue.dev, scripts |
fav_v0_* partner token | Per-Vercel-project, scoped | v0 / Vercel install only |
| OAuth bearer (15-min JWT + 30-day refresh) | Short-lived | Claude Connectors (Phase 3), ChatGPT Apps |
| OTP-issued JWT (60 min) | Short-lived | Interactive humans (merchant portal exchange) |
Marketplace tokens (fav_v0_*, OAuth-issued) are hard-blocked from superadmin tools (raw SQL, plan management) regardless of underlying scopes — defence in depth at the request layer, not just per-token RBAC.
Pricing
| Tier | Price | Limits |
|---|
| Free | $0 | 100 customers · 200 bookings/mo · 1k MCP calls/mo |
| Lite | $19 / mo | 1 seat · email comms · BYO-AI via your agent |
| Starter | $49 / mo | 3 seats · 1M AI credits · WhatsApp + SMS · meeting notes |
| Enterprise | Custom | Unlimited seats · multi-location · custom routing |
Full table: favcrm.io/pricing.
Issues / contributions
- Bugs in tool behaviour or MCP transport: open an issue here.
- Examples for a new client (Cline, Replit Agent, Roo, etc.): PRs welcome under
examples/.
- Agent workflow skills: PRs welcome under
skills/.
- Contribution guidelines:
CONTRIBUTING.md.
- Security reports: please follow
SECURITY.md; do not open public vulnerability issues.
- Server bugs / new tool requests / commercial questions: dev@favcrm.io.
Links
Brand assets
Marketplace-ready 1:1 icons with background plate, in assets/:
All icons are 1:1 aspect ratio with rounded-square plate (48px corner radius on 256-unit grid) and centered "fav." wordmark glyph.
License
This repo (docs + examples) is MIT — see LICENSE. The hosted MCP server is proprietary FavCRM SaaS; install requires a FavCRM account.
