# Zendesk Managed MCP Server > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt) --- title: Zendesk Managed MCP Server page-beta-text: This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. latest-operator-version: v26.1.5 latest-console-tag: v3.7.4 latest-connect-version: 4.96.1 latest-redpanda-tag: v26.1.10 docname: managed/zendesk page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/zendesk.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/zendesk.adoc # Beta release status page-beta: "true" description: Search and manage Zendesk Support tickets, users, and Help Center articles. Service-account API token or per-user OAuth, plus token-efficient response shaping for LLM agents. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Zendesk managed MCP server in API-token or User-OAuth mode learning-objective-2: Pick the right scopes and Zendesk role for your workflows learning-objective-3: Search, read, create, and update tickets from the Inspector or an agent page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-10" release-status: beta - This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. --- The **Zendesk** managed MCP server lets agents search, read, create, and update tickets in your Zendesk Support instance, look up users and organizations, and search, read, create, and update Help Center articles. After reading this page, you will be able to: - Configure the Zendesk managed MCP server in API-token or User-OAuth mode - Pick the right scopes and Zendesk role for your workflows - Search, read, create, and update tickets from the Inspector or an agent ## [](#what-this-mcp-server-does)What this MCP server does Wraps the Zendesk REST API. The following authentication modes are supported: - **API token (Basic authentication)**: A long-lived agent token paired with the agent’s email. Best for service-account-style use. - **User OAuth**: Per-user Zendesk OAuth tokens resolved from the gateway’s [token vault](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#token-vault). Best when you want each agent action attributed to the calling end-user. Responses are curated for token efficiency: HATEOAS URLs, transport metadata, and rarely-used fields are dropped before reaching the LLM. Related users, groups, and organizations are resolved into nested ref objects through Zendesk side-loading (single round trip), and Help Center article HTML is converted to GitHub-flavored markdown. Typical responses are 3–7× smaller than raw Zendesk JSON. It is **not** intended for Zendesk admin operations (managing macros, triggers, ticket forms, custom fields, schedules, or SLAs); use the Zendesk Admin Center or a Terraform provider for those. ## [](#prerequisites)Prerequisites Before you create the server, make sure you have: - A Zendesk Support instance. - For **API token** mode: ability to create an API token under **Apps and integrations > APIs > Zendesk API**. - For **User OAuth** mode: a Zendesk OAuth client and an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda ADP. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#get-zendesk-credentials)Get Zendesk credentials ### [](#option-1-api-token-recommended-for-service-accounts)Option 1: API token (recommended for service accounts) 1. In the Zendesk Admin Center, go to **Apps and integrations > APIs > Zendesk API**. 2. On the **Settings** tab, enable **Token access**. 3. Click **Add API token**, give it a descriptive label (for example, `redpanda-ai-gateway`), and copy the token value. It is shown only once. 4. Note the **agent email** the token will act as (the email of the user who created the token). The HTTP Basic authentication string the MCP builds is `base64(/token:)`. The `/token` literal is Zendesk’s API-token quirk. 5. Store the token in the ADP secret store under a name like `ZENDESK_API_TOKEN`. **Required role**: Agents and Admins can use the API. Most ticket operations work for the Agent role; reading users with `search_users` requires Light Agent or higher; Help Center search works for any authenticated user. ### [](#option-2-user-oauth)Option 2: User OAuth For per-user authentication, register an OAuth client on Zendesk and a matching OAuth Provider in ADP: 1. Configure a Zendesk OAuth client under **Apps and integrations > APIs > OAuth Clients** (Confidential client, Authorization Code grant). 2. Register a matching OAuth Provider in ADP. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). Use Zendesk’s authorize and token endpoints. 3. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway’s token vault. **Required scopes**: `read tickets:write hc:read hc:write` covers all tools. Drop `tickets:write` (ticket writes) and `hc:write` (article create/update) if the MCP only needs to read. ## [](#configure)Configure Create a new Zendesk MCP server in ADP: 1. Open **MCP Servers > Create Server**. 2. Pick `Zendesk` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the Zendesk configuration form: | Field | Notes | | --- | --- | | subdomain | Your Zendesk subdomain (the part before .zendesk.com). For acme.zendesk.com, set this to acme. | | auth | basic_auth for API-token mode, or user_oauth for per-user mode. | | basic_auth (API-token mode) | username (agent email used with the API token, for example agent@acme.com) and password_secret_ref (secret-store reference for the API token, UPPER_SNAKE_CASE). | | user_oauth (User-OAuth mode) | provider_name (the Zendesk OAuth Provider you configured) and the minimum required scopes (read, tickets:write, hc:read, hc:write covers all tools). | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI For a managed server, set the auth method inside the `--managed-config` JSON. The `auth` field is required. #### API-token mode ```bash rpk ai mcp create --name acme-zendesk --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme", "basic_auth": { "username": "agent@acme.com", "password_secret_ref": "ZENDESK_API_TOKEN" } }' ``` #### User-OAuth mode ```bash rpk ai mcp create --name acme-zendesk-oauth --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig", "subdomain": "acme", "user_oauth": { "provider_name": "zendesk-prod", "required_scopes": ["read", "tickets:write", "hc:read"] } }' ``` ## [](#tools)Tools The Zendesk MCP exposes tools across tickets, users, organizations, and Help Center articles. Article writes (`create_article`, `update_article`) require the `hc:write` scope (User-OAuth mode) or a Help Center manager role (API-token mode): | Tool | Description | | --- | --- | | search_tickets | Search tickets with Zendesk’s search syntax (status:open priority:high tags:bug). The handler enforces a type:ticket qualifier and post-filters results, so non-ticket records can never leak through. | | list_tickets | Filter tickets by discrete fields (status, assignee_id, group_id). Faster than search_tickets and not subject to the search-API quota. Prefer this for "show me all open tickets assigned to X" workflows. | | get_ticket | Fetch a single ticket by ID with side-loaded requester, submitter, assignee, group, and organization. Set include_comments=true to embed up to 500 comments inline in the same response. | | list_ticket_comments | List the comment thread on a ticket with explicit pagination. Use this when the thread exceeds 500 comments; otherwise prefer get_ticket with include_comments=true. | | create_ticket | Open a new ticket (subject, description, optional priority/type/assignee/group/tags). Subject ≤150 chars, description ≤65536 chars, tags ≤50 chars each. | | update_ticket | Modify a ticket: status, priority, type, assignee, group, tags. Optionally append a public or internal comment in the same call. Distinct tags (replace) / add_tags / remove_tags fields. | | search_users | Find a Zendesk user by name, email, or other user-search fields. Returns full User objects. | | get_user | Fetch a single user by ID. Used to drill into a UserRef from a side-load when the agent needs the full User shape. | | list_organizations | List organizations in the Zendesk account. | | get_organization | Fetch a single organization by ID. Drills into an OrganizationRef from a side-load. | | search_articles | Search Help Center articles. Body is converted from HTML to GitHub-flavored markdown (tables included). | | get_article | Fetch a single Help Center article by ID. | | create_article | Create a new Help Center article from markdown (converted to HTML on upload), with an optional list of labels. The article is always created as a draft, so a human must publish it in Zendesk. | | update_article | Update an existing Help Center article. Only the fields you send change; omitted fields are left as-is. Markdown is converted to HTML on upload, and you can toggle draft status or clear all labels by sending an empty label list. | ### [](#example-triage-open-tickets)Example: Triage open tickets ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_tickets", "arguments": { "query": "status:open priority:urgent", "max_results": 10 } } }' ``` ### [](#example-solve-a-ticket-with-a-closing-comment)Example: Solve a ticket with a closing comment ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "update_ticket", "arguments": { "ticket_id": 12345, "status": "solved", "add_tags": ["resolved-by-agent"], "comment": { "body": "Resetting your password should fix this. Reopen if it persists.", "public": true } } } }' ``` ### [](#example-read-a-ticket-with-its-full-comment-thread)Example: Read a ticket with its full comment thread For "summarize this ticket" flows, inline the comments: ```bash curl -s https://aigw..clusters.rdpa.co/mcp/v1/acme-zendesk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "get_ticket", "arguments": { "ticket_id": 12345, "include_comments": true } } }' ``` The handler follows Zendesk’s `next_page` URLs only when they point at the same host as the configured subdomain, so pagination cannot be hijacked by a malicious upstream response. ## [](#troubleshooting)Troubleshooting Common symptoms and fixes: | Symptom | What to check | | --- | --- | | 401 Unauthorized (API-token mode) | Confirm ZENDESK_API_TOKEN content matches the value Zendesk showed at token creation, and the Username field is the agent email of the user who created the token. | | 403 Forbidden on search_users | The agent role on Zendesk’s side is below Light Agent. Upgrade the role or use API-token mode with a Light Agent or Admin email. | | OAuthConnectionRequired (User-OAuth mode) | First call from a user with no stored token. The user completes Zendesk’s OAuth consent flow, the token lands in the vault, and subsequent calls reuse it. See User-delegated OAuth. | | scope_upgrade_required (User-OAuth mode) | Server’s required_scopes was extended after users had already consented. Users re-consent with the higher scope. | | Search returns non-ticket records | Cannot happen: the handler enforces a type:ticket qualifier and post-filters results. If you see something unexpected, file an issue. | ## [](#limitations)Limitations This page does not cover: - **Zendesk admin operations**: Managing macros, triggers, ticket forms, custom fields, schedules, or SLAs. Use the Zendesk Admin Center or a Terraform provider. - **Voice / chat / Talk**: This MCP wraps Support tickets and Help Center; voice and chat are separate Zendesk products with their own APIs. ## [](#next-steps)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)