FavCRM

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.

231 typed tools — customers, bookings, events, loyalty, invoices, payments, WhatsApp / SMS / email — exposed via MCP. Works with any agentic client that speaks Streamable HTTP transport.

The endpoint supports purpose-built tool profiles selected with ?profile=<name> or X-FavCRM-MCP-Profile:

• compact exposes a small search_tools + execute_tool discovery/router surface for large-agent runtimes.
• platform exposes only superadmin customer-workspace and company-setup operations, works without an active merchant company, and never exposes raw SQL.
• full remains the default for clients and scanners.

Platform operators can start from the dedicated Cursor or Claude Desktop configuration. Ordinary merchant API keys cannot access platform tools.

🤖 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:

1. Call register_organisation_request — server emails a 6-digit code to you
2. You paste the code back in chat
3. Agent calls register_organisation_verify — server returns a fresh fav_mcp_* key
4. 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 → 231 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:

1. claude.com → Connectors → Add custom connector
2. URL: https://api.favcrm.io/mcp
3. 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:

1. ChatGPT → Tools menu → Apps → search "FavCRM"
2. Add → OAuth handshake → workspace selector
3. 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'
# → 231

# 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

231 tools across 28 scopes. Every tool ships with annotations:

• title — human-readable label
• readOnlyHint — 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 working from a compact or context-sensitive tool set should use search_tools to discover operations, then execute_tool to run the selected tool. Use query_favcrm_platform for platform docs before guessing behavior 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
customer_segments	list_segments, preview_segment_count, set_segment_members	4	4
custom_fields	list_custom_fields, create_custom_field, set_custom_field_values	3	4
bookings	list_services, get_available_slots, create_booking	12	15
events	list_event_registrations, get_event_campaign_exclusions	2	0
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

Superadmin platform tools use a separate scope family:

Scope	Capability
platform:customer_setup	Search/create customer workspaces and configure company setup
platform:catalog	Manage global plan, module, and AI-media catalogs in the full profile
platform:sql_read	Break-glass SELECT/EXPLAIN access in the full profile
platform:sql_write	Break-glass DML access in the full profile
platform:*	All platform capabilities; reserve for controlled internal operators

SQL scopes must be explicit, and SQL tools remain unavailable in the platform profile even with platform:*.

---

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

• favcrm.io — landing page
• favcrm.io/integrations/vercel · /cursor · /chatgpt — per-platform install guides
• favcrm.io/developers — full developer docs
• favcrm.io/pricing — pricing matrix
• favcrm.io/privacy-policy · /terms-of-use

Brand assets

Marketplace-ready 1:1 icons with background plate, in assets/:

File	Use
assets/icon.png	512×512 PNG — Cursor / Smithery / mcp.so listing
assets/favcrm-icon-256-dark.svg	1:1 SVG, ink plate, light glyph — most marketplaces
assets/favcrm-icon-256-light.svg	1:1 SVG, canvas plate, ink glyph — light-themed UIs
assets/favcrm-icon-256-dark.png	256×256 PNG fallback

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.