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. Support for additional surfaces (Claude Desktop, claude.ai) is 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	Coming soon	Requires 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
• 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 Admin 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.

---

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	Verify the API key is valid and the service is reachable
tenant-get	Get organization configuration and metadata

Users

Tool	Description
user-find	Search users by name or email (partial match)
user-find-by-filter	Advanced multi-field user search
user-find-by-ids	Look up users by their IDs
user-read	Get a full user profile
user-invite	Create a new user account and send an invitation
user-update-licenses	Update product licenses for users

Workspaces

Tool	Description
workspace-list	List all workspaces in the organization
workspace-list-users	List users in a specific workspace
workspace-add-users	Add users to a workspace
workspace-remove-users	Remove users from a workspace
workspace-remove-users-all	Remove users from all workspaces

Teams

Tool	Description
team-list	List all teams
team-add-users	Add users to a team
team-remove-users	Remove users from a team
team-remove-users-all	Remove users from all teams

Distributions

Tool	Description
distribution-list	List all published distributions
distribution-create	Create a new distribution
distribution-update	Update a distribution
distribution-update-v3	Update a distribution (v3, full feature set)
distribution-adjust	Adjust distribution weights
distribution-adjust-v3	Adjust distribution weights (v3, full feature set)
distribution-delete	Delete a distribution

Routing Rules

Tool	Description
rule-list	List all active routing rules
rule-create	Create a new routing rule
rule-modify	Update an existing routing rule
rule-delete	Delete a routing rule

Meetings

Tool	Description
meeting-list	List meetings in a date range
meeting-get	Get full details for a meeting
meeting-export	Export meetings as CSV
meeting-cancel	Cancel a meeting
meeting-noshow	Mark a meeting as no-show
meeting-activity	Get the admin link for a meeting

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	List personal scheduling links for a user (returns URLs)
scheduling-link-list-round-robin	List round-robin scheduling links
scheduling-link-list-admin-one-on-one	List admin (one-on-one) scheduling links
scheduling-link-list-group	List group scheduling links
scheduling-link-list-ownership	List ownership (lead-owner) scheduling links
scheduling-link-init	Start a scheduling session for a link
scheduling-link-schedule	Book a meeting from a scheduling session
availability-combined	Check combined availability for multiple users
availability-flexible	Check flexible round-robin availability

Handoff

Tool	Description
handoff-init	Start a handoff flow (evaluate routing and availability)
handoff-schedule	Complete a handoff by booking the meeting

Concierge

Tool	Description
concierge-list-routers	List all Concierge routers
concierge-route	Execute routing logic
concierge-route-by-slug	Execute routing logic by router slug
concierge-schedule	Book a meeting from a routed session
concierge-logs	Fetch routing decision logs for a router

CRM

Tool	Description
crm-get	Look up a Chili Piper meeting by CRM event ID
crm-cancel	Cancel a meeting by CRM event ID
crm-noshow	Mark a meeting as no-show by CRM event ID
crm-activity	Get the admin link for a meeting by CRM event ID

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 and claude.ai support is 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 (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.

---