zendesk-mcp

Dedalus MCP server for Zendesk support workflows: ticket search, ticket lookup, user listing, ticket creation, internal notes or public comments, and ticket status updates.

Tools

• search_tickets - Search Zendesk tickets with Zendesk search syntax.

• get_ticket - Fetch one ticket by ID.

• list_users - List Zendesk users, optionally filtered by role.

• create_ticket - Create a new ticket with an initial public comment.

• add_ticket_comment - Add an internal note or customer-visible public comment.

• update_ticket_status - Change a ticket status.

Related MCP server: Zendesk MCP Server by Fruggr

Safety Notes

create_ticket, add_ticket_comment, and update_ticket_status are write tools. Zendesk triggers, automations, and notification settings may email customers or alter support queues. add_ticket_comment defaults to public_comment=false; set it to true only when a customer-visible reply is intended.

Do not put Zendesk OAuth access tokens, API tokens, OAuth client secrets, requester personal data, ticket bodies, or customer emails in commits, logs, issue trackers, screenshots, or public demos.

Authentication Model

This server is built for Dedalus DAuth with OAuth-style bearer tokens. The connection name is zendesk-mcp, the secret key is ZENDESK_ACCESS_TOKEN, and requests use:

Authorization: Bearer {api_key}

For a multi-user marketplace deployment, the user-specific values are:

• ZENDESK_BASE_URL: the user's Zendesk account URL, for example https://none-83105.zendesk.com.

• ZENDESK_ACCESS_TOKEN: an OAuth access token for that Zendesk account and user.

Zendesk OAuth endpoints are Zendesk-account scoped. A static Dedalus OAuth deployment with fixed OAUTH_AUTHORIZE_URL and OAUTH_TOKEN_URL only covers that one Zendesk subdomain. To support unrelated customers' own Zendesk accounts, Dedalus must receive each user's Zendesk base URL as connection/provider metadata, and the OAuth authorization must be performed against that same account.

The server code intentionally does not hardcode a Zendesk subdomain. ZENDESK_BASE_URL is only a local-smoke-test or intentional single-tenant fallback.

Dedalus Deployment

Connection settings:

Connection name: zendesk-mcp
Auth type: OAuth
Header Name: Authorization
Header Format: Bearer {api_key}

Required credentials for each end user:

ZENDESK_BASE_URL      Example: https://none-83105.zendesk.com
ZENDESK_ACCESS_TOKEN  Example: OAuth access token for that Zendesk account

If the Dedalus dashboard cannot supply per-user base_url/provider metadata to the connection, set ZENDESK_BASE_URL as an environment variable and treat the deployment as single-tenant for one Zendesk account.

Environment variables for a normal Dedalus deployment:

DEDALUS_AS_URL=https://as.dedaluslabs.ai
PORT=8080

Optional single-tenant Dedalus-managed OAuth variables:

OAUTH_ENABLED=true
OAUTH_AUTHORIZE_URL=https://<subdomain>.zendesk.com/oauth/authorizations/new
OAUTH_TOKEN_URL=https://<subdomain>.zendesk.com/oauth/tokens
OAUTH_CLIENT_ID=<zendesk-oauth-client-id>
OAUTH_CLIENT_SECRET=<zendesk-oauth-client-secret>
OAUTH_SCOPES_AVAILABLE=read,write
ZENDESK_BASE_URL=https://<subdomain>.zendesk.com

Do not set ZENDESK_ACCESS_TOKEN as a global deployment environment variable for a shared marketplace server. It must be supplied per user through DAuth credentials or OAuth.

Local OAuth Smoke Testing

Create a Zendesk OAuth client in the target Zendesk Admin Center and add this redirect URL:

http://127.0.0.1:8765/callback

Local .env minimum:

ZENDESK_BASE_URL=https://<subdomain>.zendesk.com
OAUTH_CLIENT_ID=<zendesk-oauth-client-id>
OAUTH_CLIENT_SECRET=<zendesk-oauth-client-secret>
OAUTH_SCOPES_AVAILABLE=read,write
ZENDESK_OAUTH_REDIRECT_URI=http://127.0.0.1:8765/callback

Then run:

uv run python src/oauth_local.py --write-env

The helper derives OAUTH_AUTHORIZE_URL and OAUTH_TOKEN_URL from ZENDESK_BASE_URL when they are not explicitly set, opens the browser authorization page, captures the localhost callback, exchanges the code, and writes ZENDESK_ACCESS_TOKEN to .env.

Run Locally

uv run python src/main.py

In another terminal:

MCP_SERVER_URL=http://127.0.0.1:8080/mcp uv run python src/_client.py

By default, _client.py uses ZENDESK_LOCAL_TOOL_CALLS=1, which bypasses the Dedalus MCP HTTP auth layer and calls the same tool functions through a local dispatch context. This validates the tool logic against the real Zendesk API without requiring a Dedalus-issued MCP Authorization header.

The first _client.py check is auth_check, which calls /api/v2/users/me.json and prints only masked identity data. A successful login as an end-user is not enough for the full tool suite; search, user listing, ticket creation, comments, and status updates normally require an agent or admin account.

By default, keep ZENDESK_RUN_WRITES=0 to avoid creating or updating tickets. Set ZENDESK_RUN_WRITES=1 only when you intentionally want _client.py to call create_ticket, add_ticket_comment, and update_ticket_status.

Deployed Smoke Test

For an SDK-based deployed-server smoke test, .env needs:

DEDALUS_API_KEY=dsk-live-...
DEDALUS_API_URL=https://api.dedaluslabs.ai
DEDALUS_AS_URL=https://as.dedaluslabs.ai
DEDALUS_MCP_SERVER=dedalus-labs/zendesk-mcp
ZENDESK_BASE_URL=https://<subdomain>.zendesk.com
ZENDESK_ACCESS_TOKEN=<oauth-access-token>
DEDALUS_MCP_SERVER_ONLY=1

Then run:

uv run python src/_client.py

_client.py builds a SecretValues credential with base_url=ZENDESK_BASE_URL, so the encrypted DAuth credential envelope points dispatch at the correct Zendesk account for that user.