# Kustomer MCP server > Connect Claude, ChatGPT, Cursor and other MCP clients to your Kustomer org. Install the app, add the server URL, sign in with OAuth, and let assistants search and read customers, conversations, custom objects, teams and workflows. Source: https://developer.kustomer.com/docs/ai/mcp-server The Kustomer MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. Connect an AI assistant to it, sign in with your Kustomer account, and the assistant can search and read your org's customers, conversations, messages, custom objects, teams and workflows, with your permissions. There's nothing to install or run on your machine. ```mermaid sequenceDiagram autonumber participant You participant Agent as AI assistant (Claude, ChatGPT, Cursor, …) participant MCP as Kustomer MCP server participant K as Your Kustomer org You->>Agent: "Find the most recent conversations for john@example.com" Agent->>MCP: tools/call search-customers MCP->>K: Search as you K-->>MCP: Matching customer Agent->>MCP: tools/call search-conversations MCP->>K: Search as you K-->>MCP: Conversations MCP-->>Agent: Results Agent-->>You: Three conversations, the newest about order 4417 ``` | | | | ---------------------- | -------------------------------------------------------------------- | | Server URL | `https://server.mcp.kustomerapp.com/mcp` | | One org per connection | `https://server.mcp.kustomerapp.com/orgs//mcp` | | Transport | Streamable HTTP | | Sign-in | OAuth 2.1 with PKCE, as the Kustomer user who signs in | | Access | Read-only: tools search and read, and never create, change or delete | ## Before you start #### Install the app in Kustomer An admin installs the **Kustomer MCP server** app once per org: open the **Application Store** from the left navigation, search for **Kustomer MCP server**, and select **Install**. Until it's installed, sign-in from any AI client fails with an error saying the app must be installed first. #### Check your AI client The server completes sign-in only for [approved clients](#approved-clients). ChatGPT needs an Enterprise or admin-level workspace, and Claude an admin-level workspace, because a workspace admin adds the connector for everyone. ## Connect a client Every client follows the same pattern: add a server with the URL above and **OAuth** as the authorization type, sign in to Kustomer when prompted, pick the org, and grant the requested permissions. **Claude** A workspace admin creates the connector in Claude with: - **Name**: for example, `Kustomer MCP` - **Description**: for example, "Access Kustomer data and tools directly from Claude conversations." - **MCP server URL**: `https://server.mcp.kustomerapp.com/mcp` - **Authorization**: OAuth Users then connect it and sign in. Claude calls the tools when a request needs Kustomer data, such as "Summarize the notes on this customer's latest conversation." **ChatGPT** A workspace admin creates the app in ChatGPT's admin settings with a name such as `Kustomer MCP`, a description, the MCP server URL `https://server.mcp.kustomerapp.com/mcp` and **OAuth** as the authorization type. Users install it from the workspace's app directory and sign in. Mention the app by name to use it: ```text @Kustomer MCP Find the most recent conversations for customer john@example.com. ``` **Claude Code** ```bash claude mcp add --transport http kustomer https://server.mcp.kustomerapp.com/mcp ``` Then run `/mcp` in Claude Code, choose `kustomer`, and authenticate. Claude Code signs in through a `localhost` callback on your machine. **Cursor** Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project: ```json title="mcp.json" { "mcpServers": { "kustomer": { "url": "https://server.mcp.kustomerapp.com/mcp" } } } ``` Cursor opens the Kustomer sign-in the first time it connects. **Other clients** In the client's MCP or connector settings, add a remote server with the URL and **OAuth** authorization. A client that can only start local servers over stdio can reach the hosted server through the open-source `mcp-remote` bridge: ```json title="mcp.json" { "mcpServers": { "kustomer": { "command": "npx", "args": ["-y", "mcp-remote", "https://server.mcp.kustomerapp.com/mcp"] } } } ``` ### Approved clients | Client | Connection | | ----------------------------------------------------- | ---------------- | | ChatGPT (Apps SDK and published apps) | Hosted | | Claude (web, Desktop, mobile and Cowork) | Hosted | | Cursor (desktop) | Hosted and local | | Cursor (web and Agents) | Hosted | | VS Code and GitHub Copilot | Hosted and local | | Google Antigravity, Grok, Zapier, Dust | Hosted | | Claude Code, Codex, Gemini CLI | Local | | Other local bridges, such as `mcp-remote` or Windsurf | Local | Local clients sign in through a `localhost` callback on your own machine, so any client that works that way is accepted. If a hosted platform you use isn't listed, contact Kustomer support before connecting it. ## Connect more than one org `https://server.mcp.kustomerapp.com/mcp` connects one org at a time, chosen on the sign-in screen. To stay signed in to several orgs at once, for example as an agency or with several brands, add one server per org with its own URL: ```text https://server.mcp.kustomerapp.com/orgs//mcp ``` `` is the org's Kustomer subdomain, in lowercase. Each org needs the app installed, and the org you pick when signing in must match the slug in the URL. Name each server after its org so the assistant can tell them apart. ## Tools Every tool reads. Results are trimmed to the fields an assistant needs, and lists are paged. | Area | Tools | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Search | `search` across object types, plus `search-customers`, `search-conversations`, `search-messages`, `search-companies`, `search-kobjects` and `search-notes` | | Search fields | `get--search-fields` and `get--sort-fields` for customers, conversations, messages, companies and custom objects, plus `get-search-fields` and `get-sort-fields` | | Customers and companies | `get-customers`, `get-customer-by-id`, `get-company-by-id` | | Conversations and messages | `get-conversation-by-id`, `get-messages-by-conversation`, `get-message-by-id` | | Custom objects | `list-klasses`, `get-klass`, `list-kobjects`, `get-kobject` | | Users and teams | `get-current-user`, `get-users`, `get-user-by-id`, `list-teams`, `get-team`, `get-team-by-external-id`, `get-user-teams` | | Workflows | `get-workflows`, `get-workflow-by-id`, `get-workflow-revisions`, `get-workflow-revision-by-id`, `get-workflow-variables` | The search-field tools tell the assistant which fields it can filter and sort on, including your org's custom attributes, so it can build a [search](https://developer.kustomer.com/docs/concepts/search) instead of guessing field names. Your client always shows the current list, which can grow between releases. The server also offers prompts, which clients that support them show as templates or slash commands: `customer-support-workflow`, `conversation-analysis`, `escalation-recommendation`, `customer-health-analysis` and `sla-compliance-monitoring`. ## Permissions and safety - **It acts as you.** Each person signs in with their own Kustomer account, and tools see only what that user can see. There are no shared keys to manage. - **It's read-only.** No tool creates, updates or deletes anything in Kustomer. - **Orgs stay separate.** A session is bound to the org it signed in to. A sign-in for one org is rejected on another org's URL. - **Admins decide.** Nobody in an org can connect a client until an admin installs the app. > **Assistants see real customer data:** Tool results include what the API returns, such as names, emails and message bodies. Use an AI client and model provider your organization has approved for customer data. ## Troubleshooting | Symptom | Fix | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Sign-in says the app must be installed | Ask an admin to install the **Kustomer MCP server** app in the org. | | Sign-in fails before the Kustomer login page | The client's callback isn't approved. Use a [listed client](#approved-clients) or a local bridge, or contact Kustomer support. | | `400 invalid_org_slug` | Write the org slug in the URL in lowercase. | | `403 org_slug_mismatch` | You signed in to a different org than the one in the URL. Reconnect and pick the matching org. | | `503 org_slug_unverified` | The server couldn't confirm the org. Try again. | | You're asked to sign in again | Most approved clients reconnect expired sessions without a new sign-in. If yours doesn't, reconnect the server. | | A tool returns nothing you expected | Check that your Kustomer user can see the record in Kustomer, and that you're connected to the right org. | ## Related - [Docs for AI](https://developer.kustomer.com/docs/ai/docs-for-ai): The docs MCP server, llms.txt and Markdown pages, for assistants that write code against the API. - [REST API](https://developer.kustomer.com/api): Every endpoint, for integrations that write data or need more than the MCP tools offer.