How do I connect Chili Piper via MCP?

Connect your Chili Piper account to AI coding 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 – directly from the terminal.

Note: This integration is in early access. Claude Desktop is supported today via the mcp-remote bridge (see Configure Claude Desktop); native Claude Desktop and claude.ai support are coming once OAuth 2.1 is available on the Chili Piper MCP.

Supported clients

Client	Status	Notes
Claude Code	Supported	Anthropic's terminal-based AI tool
OpenAI Codex	Supported	OpenAI's coding agent
Cursor	Supported	AI code editor
Claude Desktop	Supported	Via mcp-remote local bridge; native support coming with OAuth 2.1
claude.ai	Coming soon	Requires OAuth 2.1
ChatGPT	Not supported	No MCP support

Any tool that supports .mcp.json configuration with remote HTTP servers should work. The setup instructions below use Claude Code as the example.

Warning: The MCP server includes tools that can modify your production data – creating users, adjusting distributions, cancelling meetings, and deleting rules. Claude Code prompts for your approval before running these operations, but review each action carefully before confirming.

---

Table of Contents

• Prerequisites
• Get your API key
• Configure Claude Code
• Configure Claude Desktop
• Verify the connection
• Available tools
• Security best practices
• Limitations

---

Prerequisites

Before you begin, make sure you have:

1. Claude Code installed on your machine. Claude Code is a terminal application from Anthropic – see Anthropic's documentation for installation instructions;
2. A Chili Piper API key with the appropriate permissions for what you want to use the Chili Piper MCP for.

Note: This integration uses Chili Piper's Edge API. It does not require any additional server infrastructure on your side.

---

Get your API key

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.

---

Configure Claude Code

There are two ways to add the Chili Piper MCP server to Claude Code. Choose the option that fits your setup.

---

Option A: Personal project config (single user)

This stores the configuration in a .mcp.json file in your project directory. Add this file to .gitignore so your API key is not committed to version control.

1. Create a file called .mcp.json in the root of your project directory:

{
  "mcpServers": {
    "chili-piper": {
      "type": "http",
      "url": "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

2. Replace YOUR_API_KEY with your actual API key;
3. Add .mcp.json to your .gitignore file:

# .gitignore
.mcp.json

4. Save both files and restart Claude Code.

---

Option B: Shared project config (team setup)

This stores the server URL in a project file that can be committed to git, while each team member keeps their own API key in an environment variable.

1. Create a file called .mcp.json in the root of your project:

{
  "mcpServers": {
    "chili-piper": {
      "type": "http",
      "url": "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp",
      "headers": {
        "Authorization": "Bearer ${CHILI_PIPER_API_KEY}"
      }
    }
  }
}

2. Each team member adds the following line to their shell profile (~/.zshrc on macOS, ~/.bashrc on Linux):

export CHILI_PIPER_API_KEY="your-api-key-here"

3. Restart the terminal, then restart Claude Code.

Warning: Do not paste your actual API key into .mcp.json if this file is committed to git. Always use the environment variable pattern shown above, or add .mcp.json to your .gitignore file.

---

Configure Claude Desktop

Claude Desktop does not yet support remote HTTP MCP servers natively. As an interim path, use the mcp-remote npm package as a local bridge. Native support is coming with OAuth 2.1.

1. Install Node.js if you do not have it already (required for npx);
2. Open your Claude Desktop config file: - In Claude Desktop: go to Settings > Developer and click Edit Config. This opens claude_desktop_config.json in your default editor. - Or locate the file directly:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add the following entry under mcpServers:

{
  "mcpServers": {
    "chili-piper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://fire.chilipiper.com/api/fire-edge/v1/org/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

4. Replace YOUR_API_KEY with your actual API key;
5. Save the file, then fully quit and reopen Claude Desktop.

Warning: Your API key is stored in plaintext in claude_desktop_config.json. Protect the file with the same care as any other credential file on your machine.

---

Verify the connection

1. Open Claude Code in your terminal;
2. Type /mcp – the chili-piper server should appear in the list as connected;
3. Ask Claude: "What Chili Piper tenant is connected?" – Claude should return your organization name (e.g., "Acme Corp"). This confirms the connection is working and authenticated to the correct account.

If the server does not appear or returns an error, double-check:

• Your API key is correct and has not been revoked;
• The Authorization header includes the word Bearer followed by a space before the key;
• You restarted Claude Code after saving the config file.

---

Available tools

Once connected, Claude Code 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 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 API key)

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
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; accepts workspace filter in request body
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 all filter params in request body to avoid query-string length limits (max 7-day span)
meeting-get	Fetches full record for a single meeting by meetingId
meeting-export-v2-put	Exports meetings in a time range as CSV via v2 streaming endpoint. Accepts filter params in request body (max 7-day span)
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

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
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 dispatches the matched records to the linked executing flow

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 (Option B) or add .mcp.json to your .gitignore (Option A);
• Revoke any 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.

---

Limitations

• Early access – Claude Desktop works today through the mcp-remote bridge; native Claude Desktop and claude.ai support are coming once OAuth 2.1 is available in Chili Piper MCP;
• 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 Code 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 via distribution-adjust-v3 are additive, not absolute – if a user's current weight is 100 and you adjust by 50, the new weight is 150.

---