{
  "markdown": "# FavCRM MCP\n\n[![smithery badge](https://smithery.ai/badge/favcrm/favcrm)](https://smithery.ai/servers/favcrm/favcrm)\n\n> Install snippets, examples, and docs for the [FavCRM](https://favcrm.io) Model Context Protocol server. The server itself is hosted at `https://api.favcrm.io/mcp` — this repo is for client setup and community examples.\n\n231 typed tools — customers, bookings, events, loyalty, invoices, payments, WhatsApp / SMS / email — exposed via MCP. Works with any agentic client that speaks Streamable HTTP transport.\n\nThe endpoint supports purpose-built tool profiles selected with `?profile=<name>` or `X-FavCRM-MCP-Profile`:\n\n- `compact` exposes a small `search_tools` + `execute_tool` discovery/router surface for large-agent runtimes.\n- `platform` exposes only superadmin customer-workspace and company-setup operations, works without an active merchant company, and never exposes raw SQL.\n- `full` remains the default for clients and scanners.\n\nPlatform operators can start from the dedicated [Cursor](./examples/platform-admin.cursor.mcp.json) or [Claude Desktop](./examples/platform-admin.claude-desktop.json) configuration. Ordinary merchant API keys cannot access platform tools.\n\n## 🤖 AI Agent Skills\n\nBuilding 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:\n\n```bash\n# Example: Install the Booking Operator skill\nnpx skills add https://github.com/favcrm/mcp/tree/main/skills/favcrm-booking-operator\n\n# Or install all skills at once\nnpx skills add favcrm/mcp\n```\n\nSee the [`skills/`](./skills) directory for the full list of available agent skills.\n\nPublic agent skills live in [`skills/`](./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.\n\n| Client | Status | Setup |\n|---|---|---|\n| **Vercel v0** | ✅ Live | [Marketplace install](https://vercel.com/integrations/favcrm) — auto-provisions a workspace + injects env vars |\n| **Cursor** | ✅ Live | [`mcp.json` snippet](#cursor) |\n| **Smithery** | ✅ Live | [`smithery mcp add favcrm/favcrm`](#smithery) |\n| **Claude Desktop / Connector** | 🚧 Pending | OAuth provider (Phase 3, ~3 weeks) |\n| **ChatGPT Apps Directory** | 🚧 Pending | Listing under review |\n| **Windsurf / Continue.dev / Zed** | ✅ Works | Same `mcp.json` shape as Cursor |\n\n---\n\n## Get a key\n\nTwo ways:\n\n**Option A — your agent signs you up (no form, no portal click)**\n\nConnect FavCRM to your client first (see Cursor section below) using a placeholder env var. Then ask your agent:\n\n> \"Sign me up for FavCRM. Yoga studio called Stretch + Breathe in Hong Kong.\"\n\nThe agent will:\n\n1. Call `register_organisation_request` — server emails a 6-digit code to you\n2. You paste the code back in chat\n3. Agent calls `register_organisation_verify` — server returns a fresh `fav_mcp_*` key\n4. Agent stores the key and starts working immediately\n\nSee [`skills/favcrm-agentic-registration`](./skills/favcrm-agentic-registration) for the portable SKILL.md workflow.\n\nBehind the scenes: 10-min OTP, real email-ownership check, per-IP rate limit (3/hour, 20/day). No phishing surface, no fake demos.\n\n**Option B — sign up the traditional way**\n\n[favcrm.io/signup](https://favcrm.io/signup) → portal → `Settings → MCP Keys` → copy the `fav_mcp_*` value.\n\nExisting FavCRM merchants: same place, no plan upgrade needed for MCP access.\n\n**Free tier (both options):** 100 customers, 200 bookings/month, 1k MCP calls/month, 30-day trial of higher limits.\n\n### Bootstrap from the CLI\n\nThe `favcrm` CLI can also run the zero-state flow:\n\n```bash\nfavcrm signup request --email owner@example.com --organisation-name \"Ada Studio\"\nfavcrm signup verify --request-id <request-id> --code <code>\nfavcrm doctor\nfavcrm team invite create --email teammate@example.com --role staff\nfavcrm whatsapp status\nfavcrm whatsapp connect --mode cloud-api\n```\n\nTeam invitees can accept without an existing API key:\n\n```bash\nfavcrm team invite accept-request --token <invite-token>\nfavcrm team invite accept-verify --token <invite-token> --code <code>\n```\n\n---\n\n## Cursor\n\nVerified shape, [cursor.com/docs/mcp](https://cursor.com/docs/mcp).\n\n**`~/.cursor/mcp.json`** (or `.cursor/mcp.json` in your project):\n\n```json\n{\n  \"mcpServers\": {\n    \"favcrm\": {\n      \"url\": \"https://api.favcrm.io/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${env:FAVCRM_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nThen export the key — anywhere your Cursor process reads env vars:\n\n```bash\n# shell rc\necho 'export FAVCRM_API_KEY=fav_mcp_...' >> ~/.zshrc\n\n# or per-project (direnv)\necho 'export FAVCRM_API_KEY=fav_mcp_...' >> .envrc\n```\n\nRestart Cursor → `Settings → MCP → favcrm` connects → 231 tools land in chat.\n\n> Why `${env:VAR}` instead of inline? Cursor interpolates env vars at request time so the key never lands in your repo or shared config.\n\n---\n\n## Smithery\n\n[`favcrm.io`](https://smithery.ai/servers/favcrm/favcrm) on Smithery — install via CLI:\n\n```bash\nnpm i -g @smithery/cli\nsmithery login\nsmithery mcp add favcrm/favcrm\n```\n\nFor a project-scoped install, `smithery mcp add favcrm/favcrm --client cursor` writes the right `mcp.json` block.\n\n---\n\n## Claude Desktop\n\n🚧 OAuth-based connector pending Phase 3. Once live:\n\n1. `claude.com → Connectors → Add custom connector`\n2. URL: `https://api.favcrm.io/mcp`\n3. Authorize via OAuth → workspace selector → tool list\n\nUntil 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).\n\n---\n\n## ChatGPT\n\n🚧 Apps Directory listing under review. Once approved:\n\n1. ChatGPT → Tools menu → Apps → search \"FavCRM\"\n2. Add → OAuth handshake → workspace selector\n3. 26 curated tools land in chat (read-mostly + safe writes; destructive ops gated behind confirmation)\n\n---\n\n## Test it\n\nOnce your config is live, ChatGPT/Cursor/Claude will list tools automatically. To smoke-test from the command line:\n\n```bash\n# Discovery (no auth needed — public-scan endpoint)\ncurl https://api.favcrm.io/.well-known/mcp/server-card.json | jq '.tools | length'\n# → 231\n\n# Auth + initialize\ncurl -s https://api.favcrm.io/mcp \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"Authorization: Bearer $FAVCRM_API_KEY\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1\"}}}' \\\n  | jq\n\n# Call a read-only tool\ncurl -s https://api.favcrm.io/mcp \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"Authorization: Bearer $FAVCRM_API_KEY\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"list_membership_tiers\",\"arguments\":{}}}' \\\n  | jq\n```\n\nSee [`examples/`](./examples) for more.\n\n---\n\n## Tool surface\n\n231 tools across 28 scopes. Every tool ships with annotations:\n\n- `title` — human-readable label\n- `readOnlyHint` — `true` for `list_*` / `get_*` / `search_*` / etc.\n- `destructiveHint` — `true` for `delete_*` / `cancel_*` / `void_*` / `refund_*`\n- `openWorldHint` — `true` for tools that hit external services (WhatsApp, Stripe, email)\n- `idempotentHint` — `true` for `set_*` / `update_*` / `upsert_*` and read-only\n\nClients 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.\n\nAgents 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.\n\n| Scope | Sample tools | Read-only | Write |\n|---|---|---|---|\n| `contacts` | `search_members`, `get_member_profile`, `create_account`, `attach_tags` | 5 | 6 |\n| `customer_segments` | `list_segments`, `preview_segment_count`, `set_segment_members` | 4 | 4 |\n| `custom_fields` | `list_custom_fields`, `create_custom_field`, `set_custom_field_values` | 3 | 4 |\n| `bookings` | `list_services`, `get_available_slots`, `create_booking` | 12 | 15 |\n| `events` | `list_event_registrations`, `get_event_campaign_exclusions` | 2 | 0 |\n| `membership` | `list_tiers`, `enrol_membership`, `earn_loyalty_points` | 4 | 3 |\n| `shop` | `list_products`, `get_order`, `create_order` | 8 | 6 |\n| `invoices` | `list_invoices`, `mark_invoice_paid` | 4 | 4 |\n| `campaigns` | `list_campaigns`, `send_campaign` (gated) | 5 | 3 |\n| `blog` | `list_posts`, `publish_post` | 14 | 13 |\n\nSuperadmin platform tools use a separate scope family:\n\n| Scope | Capability |\n|---|---|\n| `platform:customer_setup` | Search/create customer workspaces and configure company setup |\n| `platform:catalog` | Manage global plan, module, and AI-media catalogs in the full profile |\n| `platform:sql_read` | Break-glass `SELECT`/`EXPLAIN` access in the full profile |\n| `platform:sql_write` | Break-glass DML access in the full profile |\n| `platform:*` | All platform capabilities; reserve for controlled internal operators |\n\nSQL scopes must be explicit, and SQL tools remain unavailable in the `platform` profile even with `platform:*`.\n\n---\n\n## Agent Issue Reports\n\nAgents 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.\n\nExample:\n\n```bash\nfavcrm 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.\"}'\n```\n\n## Plan operations\n\nAgents can inspect and preflight plan access without leaving MCP:\n\n```bash\nfavcrm tool call get_plan_status '{}'\nfavcrm tool call check_plan_operation '{\"toolName\":\"create_account\"}'\nfavcrm tool call list_plan_options '{}'\nfavcrm tool call create_plan_upgrade_link '{\"planCode\":\"favcrm-lite\",\"billingCycle\":\"monthly\",\"confirm\":true}'\n```\n\nUse `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`.\n\n---\n\n## Auth modes\n\n| Token kind | Lifetime | Use case |\n|---|---|---|\n| **`fav_mcp_*` API key** | Long-lived, revocable | Cursor, Windsurf, Zed, Continue.dev, scripts |\n| **`fav_v0_*` partner token** | Per-Vercel-project, scoped | v0 / Vercel install only |\n| **OAuth bearer (15-min JWT + 30-day refresh)** | Short-lived | Claude Connectors (Phase 3), ChatGPT Apps |\n| **OTP-issued JWT (60 min)** | Short-lived | Interactive humans (merchant portal exchange) |\n\nMarketplace 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.\n\n---\n\n## Pricing\n\n| Tier | Price | Limits |\n|---|---|---|\n| **Free** | $0 | 100 customers · 200 bookings/mo · 1k MCP calls/mo |\n| **Lite** | $19 / mo | 1 seat · email comms · BYO-AI via your agent |\n| **Starter** | $49 / mo | 3 seats · 1M AI credits · WhatsApp + SMS · meeting notes |\n| **Enterprise** | Custom | Unlimited seats · multi-location · custom routing |\n\nFull table: [favcrm.io/pricing](https://favcrm.io/pricing).\n\n---\n\n## Issues / contributions\n\n- Bugs in tool behaviour or MCP transport: [open an issue](../../issues/new/choose) here.\n- Examples for a new client (Cline, Replit Agent, Roo, etc.): PRs welcome under [`examples/`](./examples).\n- Agent workflow skills: PRs welcome under [`skills/`](./skills).\n- Contribution guidelines: [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n- Security reports: please follow [`SECURITY.md`](./SECURITY.md); do not open public vulnerability issues.\n- Server bugs / new tool requests / commercial questions: [dev@favcrm.io](mailto:dev@favcrm.io).\n\n---\n\n## Links\n\n- [favcrm.io](https://favcrm.io) — landing page\n- [favcrm.io/integrations/vercel](https://favcrm.io/integrations/vercel) · [/cursor](https://favcrm.io/integrations/cursor) · [/chatgpt](https://favcrm.io/integrations/chatgpt) — per-platform install guides\n- [favcrm.io/developers](https://favcrm.io/developers) — full developer docs\n- [favcrm.io/pricing](https://favcrm.io/pricing) — pricing matrix\n- [favcrm.io/privacy-policy](https://favcrm.io/privacy-policy) · [/terms-of-use](https://favcrm.io/terms-of-use)\n\n## Brand assets\n\nMarketplace-ready 1:1 icons with background plate, in [`assets/`](./assets):\n\n| File | Use |\n|---|---|\n| [`assets/icon.png`](./assets/icon.png) | 512×512 PNG — Cursor / Smithery / mcp.so listing |\n| [`assets/favcrm-icon-256-dark.svg`](./assets/favcrm-icon-256-dark.svg) | 1:1 SVG, ink plate, light glyph — most marketplaces |\n| [`assets/favcrm-icon-256-light.svg`](./assets/favcrm-icon-256-light.svg) | 1:1 SVG, canvas plate, ink glyph — light-themed UIs |\n| [`assets/favcrm-icon-256-dark.png`](./assets/favcrm-icon-256-dark.png) | 256×256 PNG fallback |\n\nAll icons are 1:1 aspect ratio with rounded-square plate (48px corner radius on 256-unit grid) and centered \"fav.\" wordmark glyph.\n\n## License\n\nThis repo (docs + examples) is MIT — see [`LICENSE`](./LICENSE). The hosted MCP server is proprietary FavCRM SaaS; install requires a FavCRM account.\n",
  "bytes": 14262,
  "sha": "b5b43ff48f044e94b469bc426cd11c797e9e9bf4f3565eaf93f8f3fd20071701",
  "repo_slug": "favcrm/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_favcrm_favcrm_73e6bfbe/readme"
}