Agentic Data Plane

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

The server wraps the Zendesk REST API and supports these authentication modes:

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

The server curates responses for token efficiency. It drops HATEOAS URLs, transport metadata, and rarely used fields before they reach 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.

The server isn’t 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.

  1. In the Zendesk Admin Center, go to Apps and integrations > APIs > API tokens.

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

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

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

  1. Configure a Zendesk OAuth client under Apps and integrations > APIs > OAuth Clients (Confidential client, Authorization Code grant).

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

  3. Each end user authenticates once through the OAuth flow, and the gateway stores the tokens in its 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:

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the Zendesk card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

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

  6. If the form shows Queryable, Enabled is on. Turn it off unless your agents need the two SQL tools. See Expose Zendesk data as SQL tables.

  7. Click Create server.

The create form turns Enable code mode on by default for this server type. The rpk ai mcp-server create command has no code-mode flag. To add code mode from the CLI, create a Code MCP server named <server-name>-code with --code.mcp-servers <server-name>. 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

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

Expose Zendesk data as SQL tables

The Zendesk server can also present its read operations as read-only SQL tables, so an agent can filter records the way it would query a database. SQL exposure is the Enabled toggle under Queryable in the server’s configuration. If SQL tools are available in your organization, the create form shows Queryable with Enabled on, so a server you create there is queryable unless you turn it off. Otherwise the form doesn’t show Queryable, and the server starts with SQL exposure off. Creating a server with rpk ai leaves SQL exposure off unless the managed configuration sets it. An existing server keeps the setting it was saved with. To change it, open the server’s edit form, which shows Queryable if SQL tools are available in your organization or if the server was saved with SQL exposure on. SQL exposure adds two tools:

  • list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, which columns can be filtered and with which operators, whether each filter is exact, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed.

  • execute_query: Run one query against a table and return a page of rows plus a cursor for the next page.

The tables are:

Table Contents

tickets

Support tickets, one row per ticket.

ticket_comments

The comment thread on a ticket. Every query has to filter on ticket_id, and that filter is exact because the ticket ID is passed straight through.

organizations

Zendesk organizations, one row per organization.

A page holds at most 100 rows on every table.

Neither tickets nor organizations offers any filter. The status, assignee_id, and group_id options that list_tickets accepts are not part of the tickets table, because Zendesk’s list endpoint doesn’t honor them, so execute_query refuses a predicate on those columns rather than returning rows that quietly ignore it. To find tickets by status, assignee, or group, use search_tickets. Paging a long way into tickets or organizations fails outright rather than stopping early, so scan a narrow range or search instead of walking the whole table.

With SQL exposure on, the two tools are available to every caller of the server, including agents. Turn off Enabled on a server whose agents should only reach the curated Zendesk tools.

To trim the catalog table by table, hide columns, require filters, retype a column, or serve a table under another name, use the SQL exposure tab on the server’s page. That tab works the same way for every managed type that offers SQL tables. See Narrow what the SQL tools expose. If the server’s page has no SQL exposure tab, narrowing isn’t enabled for your organization. The Enabled setting on the server’s configuration still turns the two SQL tools on and off.

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