# kusty MCP server > Give Claude Code, Cursor, Codex, Gemini CLI or any MCP client typed access to the Kustomer API. Install the kusty MCP server and /kusty skill, understand the tools it exposes, and keep agents safe with dry runs, confirmations and read-only mode. Source: https://developer.kustomer.com/docs/ai/kusty-mcp `kusty mcp serve` runs kusty as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. Every kusty command becomes a tool with a JSON Schema for its inputs, so an agent can look up a customer, read a conversation, or run an AI evaluation by name, with the same authentication, envelopes and safety rails as the [CLI](https://developer.kustomer.com/docs/ai/kusty). ```mermaid sequenceDiagram autonumber participant You participant Agent as AI client (Claude Code, Cursor, …) participant K as kusty mcp serve participant API as Kustomer API You->>Agent: "Find sam@example.com's open conversations" Agent->>K: tools/call customers.get-by-email { email } K->>API: GET /v1/customers/email=sam@example.com API-->>K: customer K-->>Agent: { schema_version, data, meta } Agent->>K: tools/call api { method: GET, path: /v1/customers/{id}/conversations, fields: [...] } K->>API: GET …/conversations API-->>K: conversations K-->>Agent: projected envelope Agent-->>You: Two open conversations, the newest about order 4417 ``` ## Install #### Install kusty and sign in Follow [Install](https://developer.kustomer.com/docs/ai/kusty#install) and [Connect an org](https://developer.kustomer.com/docs/ai/kusty#connect-an-org). The MCP server uses your active profile's credential, so check it first: ```bash kusty auth whoami ``` #### Register kusty with your AI tools ```bash kusty mcp install ``` This opens a picker of the clients kusty detects on your machine. Or choose them up front: ```bash kusty mcp install --client cursor,claude-code --yes kusty mcp install --all --yes ``` #### Restart the client Clients load MCP servers and skills at startup. After restarting, check that `kusty` is connected (in Claude Code, run `/mcp`). `kusty mcp install` writes the **absolute path** of the kusty binary into each client's configuration, so it works no matter what's on the client's `PATH`. Where the client has its own CLI, kusty uses it; otherwise it edits the config file and leaves a `.bak` copy. | Client | `--client` | Registered with | User-level config | | ----------- | ------------- | -------------------------------------------------------- | ------------------------- | | Claude Code | `claude-code` | `claude mcp add kusty --scope user -- mcp serve` | `~/.claude.json` | | Cursor | `cursor` | Config file | `~/.cursor/mcp.json` | | Gemini CLI | `gemini-cli` | `gemini mcp add kusty mcp serve` | `~/.gemini/settings.json` | | Codex | `codex` | `codex mcp add kusty -- mcp serve` | `~/.codex/config.toml` | ```bash kusty mcp status # which clients have the server and skill installed kusty mcp uninstall --all # remove both from every client ``` ### Any other MCP client Point the client at the binary with the `mcp serve` argument. For a client that reads the common `mcpServers` JSON format: ```json title="mcp.json" { "mcpServers": { "kusty": { "command": "/Users/you/.local/bin/kusty", "args": ["mcp", "serve"], "env": { "KUSTY_PROFILE": "prod" } } } } ``` Set `KUSTY_PROFILE` to pin an org, `KUSTY_READ_ONLY` to block writes, or the profile's API key variable if you use a key rather than OAuth. ## The /kusty skill By default `kusty mcp install` also installs the **`/kusty` agent skill** into each client (`--skill=false` skips it). The skill teaches the agent how to work with Kustomer through kusty: - Confirm authentication with `kusty auth whoami` before doing anything, and ask _you_ to log in rather than trying to. - Discover commands from `kusty schema dump` and `--help --json` instead of guessing endpoints. - Follow playbooks for multi-step tasks such as finding and enriching customers, bulk edits, knowledge base work, routing, and inspecting and evaluating Kustomer AI agents. - Preview writes with dry runs and confirm destructive actions with you. In Claude Code, invoke it directly: ```text /kusty find customer sam@example.com and summarize their last three conversations /kusty which of our AI agent's eval test cases failed in the latest run, and why? ``` ## Tools A session exposes 413 tools: | Tool | What it does | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.`, 411 of them | One per API operation in the [API reference](https://developer.kustomer.com/api): `customers.get-by-email`, `conversations.list`, `evaluations.runevaluation`, … | | `api` | Any request to any path, for endpoints without a named tool | | `manifest` | The full tool registry and the base URL kusty is using, so an agent can see what's available | Each named tool's input schema has the operation's path and query parameters as properties, plus: | Argument | Type | Meaning | | ---------------- | ------- | -------------------------------------------------------------------------------------------- | | `data` | object | Request body for `POST`, `PUT` and `PATCH`, with the operation's JSON Schema when one exists | | `dry_run` | boolean | Return the resolved request instead of sending it | | `validate` | boolean | Check `data` against the schema before sending. Default `true`. | | `confirm`, `yes` | boolean | Both required to run a destructive operation | The generic `api` tool takes `method`, `path`, `query` (an object of strings), `data`, `dry_run`, `confirm`, `yes`, and `fields`: ```json title="tools/call api" { "method": "GET", "path": "/v1/customers/6716a3a9c4e5f60012ab34c1/conversations", "query": { "pageSize": "25" }, "fields": ["id", "attributes.name", "attributes.status", "attributes.lastMessageAt"] } ``` `fields` keeps only the listed paths from each record. Full Kustomer records are large, so projecting lists and searches saves a lot of context. Tool results are the same [envelopes](https://developer.kustomer.com/docs/ai/kusty#the-output-contract) the CLI prints. Errors come back in-band as error envelopes with a `code` and `hint`, so the agent can read what went wrong and recover. ## Keep agents safe | Rail | How it works over MCP | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Least privilege | With OAuth, the agent acts as you, with your permissions. With an API key, give the key only the roles the agent needs. | | Read-only | Start the server with `KUSTY_READ_ONLY=true` in its environment and every write fails with `READ_ONLY`. A good default for exploration. | | Dry runs | Ask the agent to call tools with `dry_run: true` first. You see the exact method, path and body before anything changes. | | Deletes | Destructive tools refuse with `DESTRUCTIVE_CONFIRMATION_REQUIRED` unless the agent passes both `confirm` and `yes`. Agents shouldn't pass them until you say so. | | Validation | Bodies are checked against the API's schemas, so malformed writes fail before reaching Kustomer. | > **Agents see real customer data:** Tool results include whatever the API returns: names, emails, message bodies. Use an AI client and model provider your organization has approved for customer data, and prefer `fields` projections and read-only mode when you don't need more. ## Sessions and updates The client starts `kusty mcp serve` when a session begins and keeps it running. Authentication is resolved on every tool call, so an OAuth session refreshes on its own; if it can't (access was revoked, or the profile has no client secret), tools return `AUTH_REQUIRED` with a hint to run `kusty auth login`. After you update kusty, restart the client, or reconnect the server (`/mcp` in Claude Code), to load the new binary. ## Troubleshooting | Symptom | Fix | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tools don't appear | Restart the client. Check `kusty mcp status`. | | Every tool returns `AUTH_REQUIRED` | Run `kusty auth whoami` in a terminal. Log in, or export the API key variable the profile expects. Clients launched from the dock may not see variables set in your shell profile; use OAuth or put the variable in the client's MCP config. | | Session dies after 24 hours | The profile has no OAuth client secret, so it can't refresh. See [Sessions and refresh](https://developer.kustomer.com/docs/ai/kusty#sessions-and-refresh). | | Wrong org | The server uses the default profile. Set `KUSTY_PROFILE` in the server's environment. | | A new endpoint has no named tool | Use the `api` tool with the path from the [API reference](https://developer.kustomer.com/api). |