--- title: "How do I connect Chili Piper via MCP?" source_url: https://help.chilipiper.com/hc/en-us/articles/50430350863635-How-do-I-connect-Chili-Piper-via-MCP article_id: 50430350863635 updated_at: 2026-07-10T16:15:47Z --- ## Who can use this feature? Available on All Products or Routing & Scheduling Available to Only Admins [Billing Center](https://fire.chilipiper.com/fire/admin/billing/overview) [Get a Demo](https://www.chilipiper.com/request-demo?utm_source=zendesk&utm_medium=help-center&utm_campaign=chili-hub) Connect your Chili Piper account to Claude (Desktop, claude.ai web, Claude Code) and other MCP-compatible AI tools using the Model Context Protocol (MCP). Once connected, your AI assistant can read and manage your Chili Piper data – users, meetings, routing rules, distributions, and more. The server URL is the same for every client: https://fire.chilipiper.com/api/fire-edge/v1/org/mcp Authentication can be either **OAuth** (browser-based, Admin only – recommended for Claude Desktop, claude.ai, Claude Code) or **API key** (for Cursor, OpenAI Codex, or any automation/CI use case). ### Supported clients Client | OAuth | API key ---|---|--- Claude Desktop | ✅ Custom connector | – claude.ai | ✅ Custom connector | – Claude Code | ✅ `claude mcp add` | ✅ `.mcp.json` Cursor | – | ✅ `.mcp.json` OpenAI Codex | – | ✅ `.mcp.json` ChatGPT | – | – (no MCP support) > **Warning:** The MCP server includes tools that can **modify your production data** – creating users, adjusting distributions, cancelling meetings, and deleting rules. Your client will prompt for approval before running these operations, but review each action carefully before confirming. **MCP Installed? CHeck out our official skills** #### **Chili Piper Skills (AI recipes)** Which data to pull, in what order, and how to turn it into an answer you can act on. 🔗 For further details, check here [Chili Piper Skills (AI recipes)](https://help.chilipiper.com/hc/en-us/articles/52876890633235) * * * #### Table of Contents * Connect Claude Desktop or claude.ai (custom connector) * Connect Claude Code * Connect Cursor or OpenAI Codex * Verify the connection * Available tools * Security best practices * Limitations * * * ## Add via Plugin Pick the surface you work in. Options A–C install the whole set (every Skill + the Chili Piper MCP config) and keep it updated. ### **A.** Claude Desktop or claude.ai — easiest, no terminal 1. Open **Customize → Plugins** (or **Connectors**), click **＋** next to **Personal plugins** → **Create plugin → Add marketplace**. 2. Paste `https://github.com/Chili-Piper/mcp-assets` and click **Sync**. 3. Go to **Directory → Plugins** (the **Personal** tab), open the **mcp-assets** marketplace, and click **＋** on **Chili Piper Skills** to install. ### **B.** Claude Code (CLI) /plugin marketplace add https://github.com/Chili-Piper/mcp-assets /plugin install chili-piper-skills@chili-piper-skills Both the marketplace and the plugin are named `chili-piper-skills`. Hit a `git@github.com: Permission denied` SSH error? No key is needed for this public repo — run `git config --global url."https://github.com/".insteadOf "git@github.com:"` and retry. ### **C.** Just one Skill (single `.zip`) Want only one Skill — or to push a single Skill as an **Organization skill**? Download it from the [latest release](https://github.com/Chili-Piper/mcp-assets/releases/latest) and upload it via **Customize → Skills → ＋**. ### **D.** ChatGPT (Custom GPT) Each Skill has a ChatGPT equivalent. Deploy the matching Custom GPT following [gpts/README.md](https://github.com/Chili-Piper/mcp-assets/tree/main/gpts) — paste the GPT instructions, import its Actions schema, and add your Chili Piper API key as a Bearer token. ## Connect Claude Desktop or claude.ai (custom connector) OAuth-based; **you must be an Admin on a paid Chili Piper account**. No API key required. **1\. In Claude Desktop or claude.ai, open**`**Customize → Connectors**`**.** **2\. Click the**`**Add**`**button and choose**`**Add custom connector**`**.** ![](https://help.chilipiper.com/hc/article_attachments/53360816808083) **3\. In the dialog, set:** * **Name** : `Chili Piper` * **URL** : `https://fire.chilipiper.com/api/fire-edge/v1/org/mcp` * **Advanced settings** : leave the OAuth Client ID and Client Secret fields blank – they are not required. ![Add custom connector dialog with Chili Piper details](https://help.chilipiper.com/hc/article_attachments/51948173159315) **4\. Click**`**Add**`**.** You will be redirected to sign in to Chili Piper and authorize the connector. Once you approve, the connector appears in your Connectors list as `Chili Piper (Custom)`. * * * ## Connect Claude Code Two options – pick OAuth for personal use, API key for shared project configs or CI. ### Option 1: OAuth (recommended for personal use) Run one command: claude mcp add chili-piper --transport http https://fire.chilipiper.com/api/fire-edge/v1/org/mcp The first time you ask Claude Code to use a Chili Piper tool, it will open your browser for OAuth sign-in. After you approve, the token is stored locally and reused for subsequent calls. **Admin on a paid Chili Piper account required.** ### Option 2: API key (`.mcp.json`) – for non-interactive or scoped use Use the API-key path when: * Claude Code needs to run non-interactively (CI, scheduled scripts, service-account-style automation); * You need a token with a narrower permission scope than your Admin OAuth grant. See Get your API key below, then add a `.mcp.json` to your project. Two patterns – pick based on whether `.mcp.json` is committed to git: **Key pasted directly,**`**.mcp.json**`**gitignored** (simplest for solo work): { "mcpServers": { "chili-piper": { "type": "http", "url": "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } **Key from an environment variable,**`**.mcp.json**`**committed** (so a project repo can ship the config without exposing credentials): { "mcpServers": { "chili-piper": { "type": "http", "url": "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp", "headers": { "Authorization": "Bearer ${CHILI_PIPER_API_KEY}" } } } } Set the key in your shell profile (`~/.zshrc` on macOS, `~/.bashrc` on Linux): export CHILI_PIPER_API_KEY="your-api-key-here" Restart the terminal, then restart Claude Code. > **Warning:** Do not paste your actual API key into `.mcp.json` if the file is committed to git. Use the environment variable pattern above, or add `.mcp.json` to your `.gitignore`. * * * ## Connect Cursor or OpenAI Codex Cursor and Codex use the same `.mcp.json` (or equivalent config file) and API key approach as Claude Code Option 2. Generate an API key first (see Get your API key) and follow your client's MCP configuration docs, pointing it at `https://fire.chilipiper.com/api/fire-edge/v1/org/mcp` with the `Authorization: Bearer YOUR_API_KEY` header. * * * ## Get your API key You only need an API key for the API-key paths (Claude Code Option 2, Cursor, Codex). The custom-connector and `claude mcp add` OAuth paths above do not require this step. 1. In **Command Center** , go to **Integrations** in the left sidebar; 2. Select the **Credentials** tab at the top of the page; 3. Make sure you are on the **API Access Tokens** sub-tab (not HTTP Auth); 4. Click **Generate Token** ; 5. Select the permissions (scopes) your token needs, then click **Generate**. ![](https://help.chilipiper.com/hc/article_attachments/53361219913491) ![Select Permissions dialog with scope checkboxes](https://help.chilipiper.com/hc/article_attachments/51005814674963) Copy the token and store it securely – you will need it in the next step. The token is only shown once. * * * ## Verify the connection **Claude Desktop or claude.ai:** open `Customize → Connectors`. The Chili Piper connector should be listed under Web with a `Custom` tag and tool permissions visible on the right. **Claude Code:** open Claude Code in your terminal and type `/mcp` – the chili-piper server should appear in the list as connected. ![/mcp output showing chili-piper connected](https://help.chilipiper.com/hc/article_attachments/51005820246675) In either client, ask Claude: "What Chili Piper tenant is connected?" – Claude should return your organization name. This confirms the connection is working and authenticated to the correct account. If the connection does not work, double-check: * For OAuth paths: you are an Admin on a paid Chili Piper account, and you completed the sign-in step; * For API-key paths: your API key is correct, has not been revoked, and the `Authorization` header includes the word `Bearer` followed by a space before the key; * You restarted your client after adding the connector or saving the config file. * * * ## Available tools Once connected, your AI assistant has access to the following Chili Piper tools. You do not need to call these directly – Claude uses them automatically based on your questions. ### Organization Tool | Description ---|--- health-ping | Verifies API key/OAuth token is valid and service is reachable. Call first in a session – if this fails, all other calls will too tenant-get | Fetches top-level config and metadata for the authenticated org (tenant derived from credential) ### Users Tool | Description ---|--- user-find | Searches users by free-text query matched against email and name (partial matches supported) user-find-by-filter | Searches users with structured multi-field filtering using email, workspace, admin status and more user-find-by-ids | Batch-fetches profiles for multiple users by ID in a single request user-read | Fetches full profile for a single user by userId including licenses and workspace memberships user-invite | Creates a new user account and sends invitation email with optional workspace/license assignments user-update-licenses | Bulk-updates product licenses for one or more users across the organization ### Workspaces Tool | Description ---|--- workspace-list | Returns all workspaces in the org; hierarchy is Tenant → Workspaces → Teams → Users workspace-list-users | Returns users in a workspace, or all org users if no workspace ID is specified workspace-add-users | Adds users to a workspace; already-members are silently skipped workspace-remove-users | Removes users from a workspace; other memberships unaffected workspace-remove-users-all | Removes users from every workspace in the org; team memberships unaffected ### Teams Tool | Description ---|--- team-list-put | Returns all teams in the org using request body to avoid query-string length limits; supports `name` (substring) and `member` (filter teams containing all specified user IDs) filters team-add-users | Adds users to a team; already-members are silently skipped team-remove-users | Removes users from a team; non-members silently skipped team-remove-users-all | Removes users from every team in the org within specified workspaces or organization-wide ### Distributions Tool | Description ---|--- distribution-list-put | Returns all published distributions including runtime state (current per-user level, prioritization queue, on-vacation, capped, last reset); supports `name` substring + `assignmentType` (Record, Meeting, or Conversation) filters distribution-create | Creates and immediately publishes a new distribution with assignment configuration distribution-update-v3 | Replaces distribution config including weights, capping, and assignment type settings distribution-adjust-v3 | Merges adjustments into a distribution; supports all features including team reassignment distribution-delete | Permanently deletes a distribution; irreversible via API ### Rules Tool | Description ---|--- rule-list | Returns active routing rules filtered by workspace or name with pagination support rule-get | Fetches a single routing rule by its ID rule-create | Creates a new routing rule with conditions; active immediately rule-modify | Replaces rule name/conditions using optimistic concurrency control rule-delete | Soft-deletes a routing rule; removed from evaluation immediately ### Meetings Tool | Description ---|--- meeting-list-put | Returns paginated meetings in a time range. Accepts filter params in request body including `status` (Active, Canceled, NoShow, Completed); max 7-day span meeting-get | Fetches full record for a single meeting by meetingId. Returns `hostName` alongside `hostId` and `hostEmail` meeting-export-v2-put | Exports meetings in a time range as CSV via v2 streaming endpoint. Filter params include `assigneeIds`, `hostIds`, `bookerIds`, `meetingTypeIds`, `status`; max 7-day span meeting-patch | Reschedule or reassign a meeting. Supports `startTime` (new time), `hostId` (new host), and `assignees`; the service verifies availability and reserves the slot before applying changes. Sync calendar, CRM activity, and notifications automatically meeting-cancel | Permanently cancels meeting by meetingId; sets CANCELLED, may update calendar/CRM and trigger automations meeting-noshow | Marks meeting as no-show; sets NO_SHOW, may update CRM and trigger automations meeting-activity | Returns the admin UI deep-link URL for a meeting's activity page ### Scheduling Scheduling tools pair: use a list tool to discover links, then `scheduling-link-init` followed by `scheduling-link-schedule` to book a meeting. See the Scheduling Links product articles for request shapes. Tool | Description ---|--- scheduling-link-list-personal | Returns all personal scheduling links for a user scheduling-link-list-round-robin | Returns round-robin scheduling links (booking URLs backed by a distribution); all filters optional scheduling-link-list-admin-one-on-one | Returns admin (one-on-one) scheduling links – admin-provisioned links each assigned to a single fixed host scheduling-link-list-group | Returns group scheduling links – meetings with a fixed set of multiple attendees, each independently marked required or optional scheduling-link-list-ownership | Returns ownership scheduling links – links that route to the guest's account owner in the CRM (lead or contact owner) at book time scheduling-link-init | Phase 1 of 2: initializes a scheduling session from a scheduling link – fetches link metadata, queries attendee availability, stores session with available slots. Supports `outputs: ["SuggestedTimes", "SingleUseLink"]` to additionally return an inline-CSS HTML widget (paste into Gmail/Outlook drafts) and a one-time-use scheduling URL scheduling-link-schedule | Phase 2 of 2: books a meeting using a previously initialized scheduling session. Creates calendar events and sends confirmations availability-slots | Unified availability endpoint – returns slots for any attendee mix (round-robin, manual, team-assigned, additional) ### Handoff Tool | Description ---|--- handoff-init | Phase 1 of 2: initializes a handoff flow – launches workspace routers, evaluates assignee availability, stores per-path scheduling sessions, and returns routing paths with available slots handoff-schedule | Phase 2 of 2: completes a handoff by booking a meeting on the chosen path and slot. Creates calendar events and sends confirmations ### Concierge Tool | Description ---|--- concierge-list-routers | Returns all Concierge routers in the org. A router evaluates inbound lead data and routes to teams/users via rules concierge-route | Executes routing logic without an explicit slug – router resolved from body context. Behaviorally identical to concierge-route-by-slug once resolved concierge-route-by-slug | Executes routing logic for a router by slug; creates a routing session and returns a booking link for the lead concierge-schedule | Schedules a meeting for a lead at one of the time slots returned by concierge routing (requires routing was run with an interval) concierge-logs | Fetches aggregated Concierge routing decision logs for a router in a time window (max 30-day span) ### Distro Tool | Description ---|--- distro-list-routers | Returns all Distro routers in the org with id, name, and trigger resource-scheduler-run | Runs a Scheduled Trigger router on demand: executes the configured query and routes the matched records ### CRM Tool | Description ---|--- crm-get | Resolves CP meeting linked to CRM event ID and returns its full record crm-cancel | Resolves CP meeting linked to CRM event ID and permanently cancels it crm-noshow | Marks a CP meeting linked to CRM event ID as no-show crm-activity | Resolves CP meeting linked to CRM event ID and returns admin UI deep-link URL ### Example: checking your tenant ![Tenant check example](https://help.chilipiper.com/hc/article_attachments/51005829451411) ### Example: listing users ![User listing example](https://help.chilipiper.com/hc/article_attachments/51005829510547) * * * ## Security best practices * **Do not commit API keys to git.** Use environment variables, add `.mcp.json` to `.gitignore`, or use the OAuth path which doesn't expose a long-lived key; * Revoke any API keys that are no longer in use or that are suspected of being compromised; * Each team member should use their own API key – do not share a single key across the team; * The OAuth path (custom connector, `claude mcp add`) requires Admin permission and stores a per-user token. Revoke access from the Connectors panel (Desktop/web) or remove the server entry (Claude Code) when no longer needed. * * * ## Limitations * The OAuth path is currently restricted to **Admins** on paid Chili Piper accounts; API-key auth can be scoped per token using the Permissions dialog; * Some Claude Accounts may require approval from your **Claude Owner** before using the MCP and you may need to request this internally * All tool calls are scoped to your organization (tenant). You cannot access data from other Chili Piper accounts; * The tools include write operations (creating users, adjusting distributions, cancelling meetings, deleting rules). Claude asks for approval before running these, but treat confirmations with the same care as performing the action in the Chili Piper UI; * Distribution weight adjustments (both standard and v3) are **additive** , not absolute – if a user's current weight is 100 and you adjust by 50, the new weight is 150. * * *