How do I connect Chili Piper via MCP?

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.

---

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

---

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 + button next to "Connectors" and choose Add custom connector.

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.

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.

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.

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

Example: listing users

---

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;
• 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.

---