--- 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-24T18:55:56Z content_hash: 17f4f102 --- ## 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` Gemini CLI - ✅`.settings.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-desktop-or-claudeai-custom-connector) - [Connect Claude Code](#connect-claude-code) - [Connect Cursor or OpenAI Codex](#connect-cursor-or-openai-codex) - [Verify the connection](#verify-the-connection) - [Available tools](#available-tools) - [Security best practices](#security-best-practices) - [Limitations](#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 - Open **Customize → Plugins** (or **Connectors**), click **＋** next to **Personal plugins** → **Create plugin → Add marketplace**. - Paste https://github.com/Chili-Piper/mcp-assets and click **Sync**. - 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](#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](#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. ## Connect Gemini CLI Gemini CLI supports remote MCP servers over HTTP with the same API-key approach as Cursor and Codex. Generate an API key first (see "[Get your API key](https://chilipiper.zendesk.com/knowledge/editor/01KN2R0D41GTD7YJ1F9F5SVEGY/en-us?brand_id=360005231813&return_to=%2Fhc%2Fen-us%2Farticles%2F50430350863635#get-your-api-key)"), then add this to  `~/.gemini/settings/json` (or  `.gemini/settings.json` inside a project): ``` { "mcpServers": { "chili-piper": { "httpUrl": "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Restart Gemini CLI, then type `/mcp`  and the chili-piper server should appear as connected. Ask "**What Chili Piper tenant is connected?**" to confirm it is authenticated to the right account.  **Note**: newer Gemini CLI versions also accept  `"url"` with  `"type"`:  `"http"` in place of  `"httpUrl"`. ## 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. - In **Command Center**, go to **Integrations** in the left sidebar; - Select the **Credentials** tab at the top of the page; - Make sure you are on the **API Access Tokens** sub-tab (not HTTP Auth); - Click **Generate Token**; - 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.