​
Overview

The Peachdesk platform connector lets Claude work with the agents, calls, campaigns, analytics, knowledge bases, telephony configuration, and billing information in one Peachdesk organization. It uses the Model Context Protocol (MCP), so Claude discovers structured tools instead of automating the dashboard. The canonical connector URL is:
For hosted Peachdesk, use https://app.peachdeskai.com/mcp. Self-hosted deployments replace {PUBLIC_BASE_URL} with their externally reachable HTTPS origin.
Peachdesk has two separate MCP servers. This page covers the public, OAuth-protected platform connector. Voice Studio’s MCP server is a local service with different tools and a different connection method.

​
Before you connect

  • You need a Peachdesk account and membership in the organization Claude should use.
  • The connector URL must be reachable from Anthropic over HTTPS. A loopback URL is suitable only for local Claude Code testing.
  • A connector authorization is pinned to one organization. Changing your active organization in Peachdesk does not move an existing grant; authorize a new connection to work in another organization.

​
Connect from claude.ai

1

Open the custom connector form

Go to Customize → Connectors → + → Add custom connector.
2

Enter the connector details

Choose a name such as Peachdesk and enter {PUBLIC_BASE_URL}/mcp. Leave Advanced client credentials empty. Peachdesk uses Dynamic Client Registration (DCR), so Claude registers a public client and does not need a client secret.
3

Add and connect

Select Add or Connect, sign in to Peachdesk, choose one organization, review the requested scopes, and approve the scopes you want to grant.
4

Enable it in a conversation

Open the conversation’s connector controls, enable Peachdesk, and confirm that the permitted tools appear.
For Team and Enterprise plans, an Owner or Primary Owner first adds the remote MCP URL under Organization settings → Connectors. Each member then connects their own Peachdesk account under Customize → Connectors. Claude’s custom-connector UI does not edit an existing connector’s URL or credentials in place. Remove the connector and add it again when either changes. Peachdesk allows public clients to register dynamically. Peachdesk does not vet each application, and the displayed application name is whatever that application claims it is. Check the exact redirect URL shown on the consent screen and approve only a connection you started yourself.

​
Connect from Claude Code

​
Use your Claude account connector

If Claude Code is signed in with the same Claude account:
  1. Add Peachdesk in the claude.ai connector UI once.
  2. Run /mcp in Claude Code.
  3. Select the Peachdesk account connector and authenticate if prompted.
  4. Verify the tool list before using it.

​
Add the URL with the CLI

Use this path for a direct Claude Code registration:
Choose the narrowest configuration scope that fits:
  • --scope local — one developer in one repository.
  • --scope user — one developer across all repositories.
  • --scope project — only when the team intends to commit and share .mcp.json.
Never commit client secrets or tokens to .mcp.json. Inspect an existing entry with claude mcp list and claude mcp get <name> before replacing it.

​
OAuth scopes

You can approve a subset of the scopes requested by the client. The tool list and every tool call are filtered server-side using the approved subset.

​
Not in v1

These permissions are deliberately not grantable in v1:
  • agents:publish — publish or archive an agent from the Peachdesk dashboard.
  • analytics:write — manage saved charts in the Analytics dashboard.
  • telephony:write — change a number’s inbound agent or default caller ID under Telephony configurations.
The connector also cannot read provider credentials: no OAuth scope exists for them. Security and account settings, organization settings, payments and billing writes, API keys, and member or invitation management remain user-only. When possible, Claude returns a Peachdesk link so you can complete such an action in the dashboard.

​
Approval for calls and campaign runs

Approving calls:run or campaigns:run on the OAuth consent screen grants access to the preview tools. It is not approval to dial. When you ask Claude to place a call or start or resume a campaign:
  1. Claude creates a preview and returns a link to a Peachdesk approval page.
  2. The page shows the specific campaign or phone-number target and its bounds.
  3. Nothing is dialled until the signed-in grant owner selects Approve and run there.
  4. Peachdesk durably queues the approved action; you can leave the page open to see Queued, Running, and the final outcome. Claude can read the same status without running it again.
  5. The approval is single-use, expires, and is tied to that target snapshot.
  6. Changing the target invalidates the approval and requires a new preview.
If Peachdesk cannot determine whether a provider accepted an outbound action, the final state is Outcome unknown. Do not ask Claude to retry it. Have an operator reconcile the provider and Peachdesk records first so a retry cannot contact the person twice. Tenant owners and admins can configure narrowly bounded standing policies for a platform-verified, tenant-enabled connector. A matching policy can queue only its exact action, target snapshot, absolute UTC window, destination boundary, and use/contact limits. Cost estimates are display-only; they never authorize spend. If any grant, membership, connector identity, tenant enablement, target, or policy becomes stale, Peachdesk falls back to human approval or refuses the action. Inline approval inside the connector chat is not enabled in this release. Peachdesk always uses the authenticated approval URL; client flags, model text, and generic MCP capability claims cannot replace the signed-in user’s decision. Claude saying that you confirmed in chat is not approval. Tool requests and model output are treated as untrusted until the separate Peachdesk approval is recorded and consumed.

​
Retry write operations safely

Write tools accept an optional idempotency_key. Repeating the same tool call with the same key and arguments returns the original result instead of creating a second resource. Reusing the key with different arguments is an error. Use a new key for a genuinely new operation.

​
Revoke a connection

Open Peachdesk Account (/account), find Connected apps, and select Revoke. Revocation immediately invalidates the grant’s access and refresh tokens. Remove the connector in Claude as the client-side half; removing it only from Claude does not replace server-side revocation.

​
Legacy API-key clients

The existing /api/v1/mcp alias remains supported for API-key integrations, but OAuth at /mcp is recommended for new connections because it is per-user, scoped, and revocable.
The compatibility path now requires the API key for initialize and tools/list; those operations were previously anonymous. API keys are organization-wide and carry no OAuth scopes, so treat YOUR_API_KEY as a full-organization credential. Never commit it or paste it into a shared chat.

​
Example prompts

Explore your workspace
  • “List my agents in Peachdesk.”
  • “Show me the draft definition of the agent called Lead Qualifier.”
  • “List recent calls and summarize their outcomes.”
  • “Show my current credit balance.”
Create bounded drafts
  • “Create a draft agent for lead qualification.”
  • “Create a campaign draft from this contact list, but do not start it.”
  • “Add this text to the Support knowledge-base collection.”
Request a real-world action
  • “Preview starting the August follow-up campaign and give me the Peachdesk approval link.”
  • “Preview a call to this customer using Support Bot. Do not dial until I approve it in Peachdesk.”
Agent edits are saved as a new draft version. Your published agent keeps serving calls until you explicitly publish the draft from the Peachdesk dashboard.

​
Self-hosted and local testing

For the all-in-Docker stack, the API port is not published to the host. Reach the connector through the configured edge or cloudflared URL and set PUBLIC_BASE_URL to that externally reachable origin. Do not give Claude http://localhost:8000/mcp for that deployment shape. For contributor development, run only Postgres, Redis, and MinIO from docker-compose-local.yaml; the centrally managed host uvicorn process owns port 8000. A loopback PUBLIC_BASE_URL=http://localhost:8000 is then suitable for a local Claude Code client, but not for claude.ai. Before switching between the -p peachdesk full stack and the directory-named local dependency stack, run docker compose -p peachdesk down (or bring down the local stack when switching the other way). This avoids leaving a container attached to a network the next stack needs to replace.
Remote self-hosted installs may initially use a self-signed certificate. Claude Code rejects it unless the CLI is started with TLS verification disabled:
Use this only for temporary local/self-signed testing. Configure a trusted custom domain certificate before exposing the connector broadly.

​
Optional Google sign-in

Operators using the local auth provider can set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in the backend environment and register {PUBLIC_BASE_URL}/api/v1/auth/google/callback in Google Cloud. Both variables must be set for the button and routes to become available. These are backend-only secrets; never use a NEXT_PUBLIC_ variable or put them in ui/.env.

​
Troubleshooting

  • The endpoint returns 401. This is the expected unauthenticated response. Its WWW-Authenticate header points the client to Peachdesk’s protected-resource metadata so OAuth can begin.
  • The connector was added but shows no tools. Reconnect and approve the scopes needed for those tools. Tool discovery is scope-filtered.
  • The wrong organization appears. Revoke the grant and authorize a new connection for the intended organization; a grant never follows the dashboard’s active-organization switch.
  • Claude Code rejects a self-signed certificate. Use the temporary development workaround above or install a trusted certificate.
Peachdesk records the request ID, tool name, subject, organization, outcome, and latency for connector calls. It does not record tool arguments or results in the connector audit log or tracing payloads.