Agentic Data Plane

Preview

Zendesk Managed MCP Server

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

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

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

Before you create the server, make sure you have:

A Zendesk Support instance.
For API token mode: the Zendesk Admin role, which is required to create an API token, and API token access turned on for your account.
For User OAuth mode: a Zendesk OAuth client and an OAuth Provider configured in Redpanda Agentic Data Plane. See Configure an OAuth Provider.

Get Zendesk credentials

Choose the credential that matches your authentication mode. Use an API token for service-account access, or an OAuth client for User OAuth.

Option 1: API token (recommended for service accounts)

In the Zendesk Admin Center, go to Apps and integrations > APIs > API tokens.
Click Add API token, optionally enter a description (for example, redpanda-ai-gateway), and click Save. Copy the token value. It is shown only once.
Choose the email of the Zendesk user the server acts as. A Zendesk API token isn’t tied to the user who created it, so this email decides whose identity and role the tool calls use. The HTTP Basic authentication string the MCP builds is base64(<email>/token:<api_token>).
Store the token in the Agentic Data Plane 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

For per-user authentication, register an OAuth client on Zendesk and a matching OAuth Provider in Agentic Data Plane:

Configure a Zendesk OAuth client under Apps and integrations > APIs > OAuth Clients (Confidential client, Authorization Code grant).
Register a matching custom OAuth Provider in Agentic Data Plane. See Configure an OAuth Provider. Set the authorization endpoint to https://<subdomain>.zendesk.com/oauth/authorizations/new and the token endpoint to https://<subdomain>.zendesk.com/oauth/tokens, and add two scopes, read and write, one per field.
Each end user authenticates once through the OAuth flow, and tokens are stored in the gateway’s token vault.

Required scopes: read and write together cover all tools. Use read alone if the server only needs to read.

Set required_scopes only to scopes that the OAuth Provider requests. Agentic Data Plane compares scope names exactly. If you require a scope that the OAuth Provider doesn’t request, tool calls fail with scope_upgrade_required until each user reconnects and grants it. If the Zendesk OAuth client isn’t allowed to grant that scope, every tool call keeps failing.

Configure

Create a new Zendesk MCP server in Agentic Data Plane:

Open MCP servers in the sidebar.
Click Add MCP server.
Click the Zendesk card in the marketplace picker.
Replace the suggested Name, and optionally add a Description.

In the Zendesk configuration form:

Field Notes

Field	Notes
`subdomain`	Your Zendesk subdomain (the part before `.zendesk.com`). For `acme.zendesk.com`, set this to `acme`.
`Auth Method`	`Basic Auth` for API-token mode, or `User OAuth` for per-user mode (`basic_auth` or `user_oauth` in the CLI JSON).
`basic_auth` (API-token mode)	`username` (the email of the Zendesk user the server acts as, 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 required scopes (`read write` covers all tools, a subset of the provider’s scopes).

subdomain

Your Zendesk subdomain (the part before .zendesk.com). For acme.zendesk.com, set this to acme.

Auth Method

Basic Auth for API-token mode, or User OAuth for per-user mode (basic_auth or user_oauth in the CLI JSON).

basic_auth (API-token mode)

username (the email of the Zendesk user the server acts as, 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 required scopes (read write covers all tools, a subset of the provider’s scopes).

Click Create server.

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create leaves it off unless you pass --code-mode. See Code Mode.

Configure from the CLI

For a managed server, set the authentication method inside the --managed.config JSON. The auth field is required.

API-token mode
User-OAuth mode

rpk ai mcp-server create acme-zendesk --enabled --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"
  }
}'

rpk ai mcp-server create acme-zendesk-oauth --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.zendesk.v1.ZendeskMCPConfig",
  "subdomain": "acme",
  "user_oauth": {
    "provider_name": "zendesk-prod",
    "required_scopes": ["read", "write"]
  }
}'

Tools

The Zendesk MCP exposes tools across tickets, users, organizations, and Help Center articles. Article writes (create_article, update_article) require the write scope (User-OAuth mode) or a Help Center manager role (API-token mode):

Tool Description

Tool	Description
`search_tickets`	Search tickets with Zendesk’s search syntax (`status:open priority:high tags:bug`). The server adds a `type:ticket` qualifier and post-filters results, so non-ticket records can never leak through.
`list_tickets`	List tickets page by page. The tool accepts `status`, `assignee_id`, and `group_id`, but Zendesk’s List Tickets endpoint doesn’t document those filters, so results might include tickets that don’t match them. To find tickets by status, assignee, or group, use `search_tickets` (for example, `status:open assignee:X`).
`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 use `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 in a section (`section_id` is required) 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.

search_tickets

Search tickets with Zendesk’s search syntax (status:open priority:high tags:bug). The server adds a type:ticket qualifier and post-filters results, so non-ticket records can never leak through.

list_tickets

List tickets page by page. The tool accepts status, assignee_id, and group_id, but Zendesk’s List Tickets endpoint doesn’t document those filters, so results might include tickets that don’t match them. To find tickets by status, assignee, or group, use search_tickets (for example, status:open assignee:X).

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 use 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 in a section (section_id is required) 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

curl -s https://aigw.<cluster-id>.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

curl -s https://aigw.<cluster-id>.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

For "summarize this ticket" flows, inline the comments:

curl -s https://aigw.<cluster-id>.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 server follows Zendesk’s next_page URLs only when they point at your configured subdomain.

Troubleshooting

Common symptoms and fixes:

Symptom What to check

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 email of an active Zendesk user.
`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.
`connection_required` (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)	The server’s required scopes were extended after users consented, so users reconnect to grant them. If it persists after reconnecting, a required scope is missing from the provider’s scopes or from the Zendesk OAuth client.
`list_tickets` returns tickets outside the requested status, assignee, or group	Zendesk’s List Tickets endpoint doesn’t document those filters. Use `search_tickets` with a query such as `status:open assignee:X` instead.

401 Unauthorized (API-token mode)

Confirm ZENDESK_API_TOKEN content matches the value Zendesk showed at token creation, and the Username field is the email of an active Zendesk user.

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.

connection_required (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)

The server’s required scopes were extended after users consented, so users reconnect to grant them. If it persists after reconnecting, a required scope is missing from the provider’s scopes or from the Zendesk OAuth client.

list_tickets returns tickets outside the requested status, assignee, or group

Zendesk’s List Tickets endpoint doesn’t document those filters. Use search_tickets with a query such as status:open assignee:X instead.

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

Was this helpful?

group Ask in the community

mail Share your feedback