kusty MCP server

kusty mcp serve runs kusty as a Model Context Protocol 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.

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

1. Install kusty and sign in

   Follow Install and Connect an org. The MCP server uses your active profile's credential, so check it first:

   Shell

   kusty auth whoami

2. Register kusty with your AI tools

   Shell

   kusty mcp install

   This opens a picker of the clients kusty detects on your machine. Or choose them up front:

   Shell

   kusty mcp install --client cursor,claude-code --yes
   kusty mcp install --all --yes

3. 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.

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:

{
  "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:

/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:

Each named tool's input schema has the operation's path and query parameters as properties, plus:

The generic api tool takes method, path, query (an object of strings), data, dry_run, confirm, yes, and fields:

{
  "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 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

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