zendesk-mcp
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 11 GitHub stars
Code Gecti
- Code scan — Scanned 5 files during light audit, no dangerous patterns found
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
A Model Context Protocol server for Zendesk in C# / .NET 10 — tickets, users, views, macros and Help Centre search, with stdio and HTTP transports and an OAuth 2.1 bridge to Microsoft Entra ID for use from Claude web.
Zendesk MCP server
A Model Context Protocol server for Zendesk, written in C# (.NET 10).
It gives Claude — and any other MCP client — access to the Zendesk support desk: tickets, comments,
users, organisations, groups, views, macros and the Help Centre knowledge base, plus a generic escape
hatch that reaches any Zendesk REST API v2 endpoint.
Credit: this project grew out of reminia/zendesk-mcp-server,
the original Python Zendesk MCP server — thanks to reminia for showing the way.
Highlights:
- A broad tool set, including ticket search and views (so you can filter, for example, one
team's open tickets). - Two transports from one build:
stdiofor running locally, andhttpfor hosting so it can be
used from Claude web (and remote Claude Code) over HTTPS with OAuth. - Optional per-user Zendesk agents: when people sign in with their work accounts, each person can
act as a Zendesk agent you choose for them, and anyone you have not listed is turned away.
Contents
- Tools
- Pick how you want to run it
- Configuration reference
- Path 1 — Local Docker (stdio)
- Path 2 — Self-hosted HTTP (API key)
- Path 3 — Azure: hosted HTTPS with OAuth (Claude web)
- Connecting a client
- How authentication works
- Troubleshooting
- Security notes
- Project structure & development
Tools
| Area | Tools |
|---|---|
| Tickets | get_ticket, get_tickets, search_tickets, create_ticket, update_ticket, delete_ticket |
| Comments | get_ticket_comments, create_ticket_comment |
| Attachments | get_ticket_attachment (images only, validated, 10 MB cap) |
| Users | get_current_user, get_user, list_users, search_users, create_user, update_user |
| Organisations | get_organization, list_organizations, search_organizations |
| Groups | list_groups, get_group |
| Views | list_views, get_view, get_view_tickets |
| Macros | list_macros, get_macro |
| Help Centre | search_articles (plus the zendesk://knowledge-base resource) |
| Anything else | zendesk_request — call any Zendesk REST API v2 endpoint directly |
It also provides two prompts: analyze-ticket and draft-ticket-response.
Pick how you want to run it
There are three ways to run the server. Start at the top — each path is a superset of the one above it.
| # | Path | Transport | Who can connect | Auth to the server | Effort |
|---|---|---|---|---|---|
| 1 | Local Docker | stdio |
Claude Code / any local MCP client on your machine | none (you run it) | minutes |
| 2 | Self-hosted HTTP | http |
anything that can reach the host + has the key | shared API key header | small |
| 3 | Azure + OAuth | http |
Claude web and remote clients | Microsoft Entra ID OAuth 2.1 | most |
All three use the same build and the same Zendesk credentials. By default every request is sent as one
shared agent (see How authentication works); Path 3 can instead send each
signed-in person's requests as their own agent (see Per-user Zendesk agents).
The only other differences are the transport and how clients authenticate to the server.
The hosting steps below use Azure as the worked example because the OAuth bridge ships ready for
Microsoft Entra ID. Nothing forces that choice: the container is a plain ASP.NET app, so you can run
Path 2 on any host (a VM, Kubernetes, Fly.io, Render, …), and the OAuth concepts in Path 3 map onto
any reverse proxy + identity provider.
Configuration reference
Every setting can be supplied as an environment variable (handy with --env-file) or viaappsettings.json. Environment variables use __ (double underscore) for nested keys, e.g.OAuth__ExternalBaseUrl ↔ OAuth:ExternalBaseUrl.
Always required (talking to Zendesk)
| Setting | Env var | Example | Notes |
|---|---|---|---|
| Subdomain | ZENDESK_SUBDOMAIN |
acme |
for acme.zendesk.com |
| Agent e-mail | ZENDESK_EMAIL |
[email protected] |
the account actions are attributed to (not used when ZENDESK_USER_LOGIN_MODE is Mapped) |
| API token | ZENDESK_API_TOKEN |
… |
created in Zendesk Admin Centre → Apps and integrations → APIs → Zendesk API |
Copy .env.example to .env and fill these in.
HTTP transport
| Setting | Env var | Required when | Notes |
|---|---|---|---|
| Transport | TRANSPORT |
always (http) |
stdio (default) or http |
| API key | MCP_API_KEY (Mcp:ApiKey) |
non-production HTTP | shared secret; sent by clients as the X-API-Key header. Ignored in Production (Production uses OAuth instead — see below). |
Production OAuth (Path 3 only)
In Production the API-key middleware is off and the server validates Microsoft Entra ID JWTs and
runs the OAuth bridge. These map to the AzureAd and OAuth config sections:
| Setting | Env var | Example | Notes |
|---|---|---|---|
| Tenant ID | AzureAd__TenantId |
<tenant-guid> |
your Entra tenant |
| Client ID | AzureAd__ClientId |
<client-guid> |
the app registration |
| Audience | AzureAd__Audience |
api://<client-guid> |
token audience the API accepts |
| OAuth client ID | OAuth__ClientId |
<client-guid> |
same app registration |
| OAuth tenant ID | OAuth__TenantId |
<tenant-guid> |
|
| OAuth scopes | OAuth__Scopes |
api://<client-guid>/mcp.read openid profile offline_access |
space-delimited; include offline_access for refresh tokens |
| External base URL | OAuth__ExternalBaseUrl |
https://your-gateway.example.com |
the public gateway origin (no trailing path) |
| Route prefix | OAuth__RoutePrefix |
zendesk-mcp |
the public path the server is exposed under — must match your gateway API path (default mcp) |
ExternalBaseUrl + RoutePrefix are how the server advertises its own OAuth URLs, e.g.https://your-gateway.example.com/zendesk-mcp/authorize. Getting these two right is the single most
important part of Path 3 — see the OAuth discovery note.
Per-user Zendesk agents (Path 3 only)
By default every request goes to Zendesk as the one agent in ZENDESK_EMAIL. When people sign in with
their own work accounts (Path 3), you can instead choose which Zendesk agent each person acts as, and
turn away anyone you have not listed.
| Setting | Env var | Example | Notes |
|---|---|---|---|
| User login mode | ZENDESK_USER_LOGIN_MODE (Zendesk:UserLoginMode) |
Mapped |
Shared (default): everyone acts as ZENDESK_EMAIL. Mapped: each signed-in person acts as their mapped agent, and anyone else is refused. |
| User mappings | ZENDESK_USER_MAPPINGS (Zendesk:UserMappings) |
[email protected][email protected]; [email protected][email protected]; [email protected] |
Required in Mapped mode. Ignored (with a startup warning) in Shared mode. |
How to write the mapping:
Each entry is
sign-in address=Zendesk agent address, e.g.[email protected][email protected].An address on its own maps to itself:
[email protected]is short for[email protected][email protected].Separate entries with
;,,or new lines. Several people can share one agent. Case is ignored.Hosting platforms such as App Service don't allow
@in setting names, so put the whole mapping
in the one setting's value (ZENDESK_USER_MAPPINGSorZendesk__UserMappings).In
appsettings.jsonyou can also give a list:"Zendesk": { "UserLoginMode": "Mapped", "UserMappings": [ "[email protected][email protected]", "[email protected][email protected]", "[email protected]" ] }
What to know:
- Which address is matched. The server reads the person's sign-in address from their Entra ID token
(preferred_username, thenupn, thenemail). For members of your tenant this is their user
principal name, which in most organisations is also their e-mail address. If a mapping doesn't match,
the server log shows the address it saw. - One token, many agents. Each mapped Zendesk address must be an agent or admin in your Zendesk
account. A Zendesk API token works with any agent's e-mail, so the oneZENDESK_API_TOKENcovers
everyone.ZENDESK_EMAILis not used. - Who gets refused, and where. Someone outside the mapping is stopped at sign-in (the OAuth callback
sendsaccess_deniedback to their client) and again on every MCP request (403). A request with no
valid sign-in gets401. The health check and OAuth endpoints stay open, because people need them to
sign in. - Entra sign-in is required.
Mappedmode needs to know who is calling, so it works only with the
HTTP transport in Production. The server refuses to start inMappedmode on stdio or with the API
key (Paths 1 and 2), or with an empty or malformed mapping. - Changes need a restart. The mapping is read at startup. On App Service, saving the app settings
restarts the app. Once restarted, someone you removed is refused even if their token is still valid. - Shared knowledge base. The
zendesk://knowledge-baseresource is cached for an hour and shared by
everyone, whichever agent fetched it.
Path 1 — Local Docker (stdio)
The simplest option, and all you need for Claude Code on your own machine.
# Build the image (from the repository root)
docker build -f src/ZendeskMcp.Server/Dockerfile -t zendesk-mcp .
# Run it — the -i flag keeps stdin open for the MCP protocol
docker run --rm -i --env-file .env zendesk-mcp
The server starts in stdio mode by default: logs go to stderr, and the JSON-RPC protocol uses stdout.
There is nothing to authenticate — you launched the process, so you already have access.
Prefer no Docker?
dotnet run --project src/ZendeskMcp.Server # stdio
Jump to Connecting a client to wire it into Claude Code.
Path 2 — Self-hosted HTTP (API key)
Run the same image in HTTP mode behind any host you control. A shared API key gates access. This is
ideal for a shared team server, a remote Claude Code setup, or any non-browser MCP client.
docker run --rm \
-e TRANSPORT=http \
-e MCP_API_KEY=choose-a-strong-secret \
-p 8080:8080 \
--env-file .env \
zendesk-mcp
The server listens on :8080. Clients must send X-API-Key: <your secret> on every request. Health
check: GET /healthz (always anonymous).
Put it behind TLS (a reverse proxy such as Caddy, nginx, or your platform's ingress) before exposing it
beyond localhost. That's everything most self-hosters need.
Why not use the API key with Claude web? Claude web only connects to MCP servers that implement
the OAuth flow — it has no place to put a static header. For Claude web you need Path 3.
Path 3 — Azure: hosted HTTPS with OAuth (Claude web)
This is the full setup: the container runs in Production mode, a reverse proxy / gateway terminates
TLS and validates OAuth tokens, and the server itself acts as a small OAuth 2.1 authorization server
that bridges to your identity provider. The worked example uses Azure App Service + Azure API
Management (APIM) + Microsoft Entra ID, which the code supports out of the box.
Claude web ──HTTPS──▶ API Management ──▶ App Service (this container, TRANSPORT=http, Production)
│ • validates Entra JWT │
│ • CORS for the browser ├─ /<prefix>/.well-known/... (OAuth discovery)
└─ OAuth 2.1 ◀──────────────────────────────────── ├─ /<prefix>/authorize|token|register|oauth-callback
(bridged to Entra ID) └─ /<prefix> (the MCP endpoint, JWT-protected)
Step 1 — Create the Entra ID app registration
In Microsoft Entra ID → App registrations → New registration:
- Expose an API: set the Application ID URI to
api://<client-id>. - Add a delegated scope, e.g.
mcp.read. This becomes part ofOAuth__Scopes. - Under Authentication, add a Web redirect URI:
https://your-gateway.example.com/<route-prefix>/oauth-callback
(e.g..../zendesk-mcp/oauth-callback). This must exactly matchExternalBaseUrl+RoutePrefix. - (Do this last, after Step 2.) The server exchanges the auth code with Entra using a federated
identity credential rather than a client secret. Once the App Service exists, add a federated
credential on the app registration whose subject is the App Service's managed identity. (SeeAuth/OAuthEndpoints.cs— the callback and the token endpoint's refresh grant useManagedIdentityCredential+ a client assertion.) No client secret to store or rotate.
Step 2 — Deploy the container to App Service
Create an App Service (Linux, container) and deploy this image (the included GitHub Actions workflow
can do it — see Step 4). Set these application settings:
TRANSPORT=http
ASPNETCORE_ENVIRONMENT=Production
AzureAd__TenantId=<tenant-guid>
AzureAd__ClientId=<client-guid>
AzureAd__Audience=api://<client-guid>
OAuth__ClientId=<client-guid>
OAuth__TenantId=<tenant-guid>
OAuth__Scopes=api://<client-guid>/mcp.read openid profile offline_access
OAuth__ExternalBaseUrl=https://your-gateway.example.com
OAuth__RoutePrefix=zendesk-mcp
ZENDESK_SUBDOMAIN=... # ideally Key Vault references
ZENDESK_EMAIL=...
ZENDESK_API_TOKEN=...
# Optional — per-user Zendesk agents (see the configuration reference):
# ZENDESK_USER_LOGIN_MODE=Mapped
# [email protected][email protected]; [email protected]
Enable the App Service's system-assigned managed identity (needed by Step 1.4). Keep the App Service
private to the gateway if you can (access restrictions / private endpoint), so the only public door is
APIM.
Step 3 — Put API Management in front
Import an API in APIM with the API URL suffix = your route prefix (e.g.
zendesk-mcp). This
must equalOAuth__RoutePrefix.Set the API's backend (
serviceUrl) to the App Service, e.g.https://your-app.azurewebsites.net.Apply the inbound policy from
apim-policies/zendesk-mcp-policy.xml.
It: allows CORS forhttps://claude.ai; lets the OAuth discovery/flow paths through without JWT;
requires a valid Entra JWT on every other request; injects the backendX-API-Key; and on a 401
returns aWWW-Authenticateheader pointing at the protected-resource metadata so the client knows
how to start the OAuth flow.Define the named values the policy references (see
apim-policies/README.md):Named value What it is EntraIDTenantIdyour tenant ID ZendeskMcpClientIdthe app registration's client ID (audience api://<client-id>)ZendeskMcpApiKeythe shared X-API-Keythe backend expects (Mcp:ApiKey); store in Key VaultAPIMGatewayURLthe public gateway origin, e.g. https://your-gateway.example.comUse server-specific names (the
ZendeskMcp…prefix) so multiple MCP APIs on one gateway don't collide.
CORS gotcha: the 401 error response must carry CORS headers (the policy's
<on-error>block
does this). If it doesn't, the browser hides theWWW-Authenticateheader and Claude web never starts
the OAuth flow. This is the most common "it just silently doesn't connect" cause.
OAuth discovery on a shared gateway
This is subtle and worth understanding, because it's the difference between "connects" and "fails with a
confusing error". When a client connects, it discovers where to authenticate like this:
- Hits the MCP endpoint → gets
401withWWW-Authenticate: …resource_metadata="…/<prefix>/.well-known/oauth-protected-resource". - Fetches that protected-resource document → reads its
authorization_serversentry. - Treats that entry as the issuer and fetches the authorization-server metadata to learn the
authorize/token/registerendpoints.
Two rules make step 2–3 work when several servers share one gateway host:
- Advertise the issuer with your route prefix. The server sets
authorization_serversandissuerto{ExternalBaseUrl}/{RoutePrefix}(e.g.https://your-gateway.example.com/zendesk-mcp),
not the bare host. If you advertise the bare host, a client resolves the gateway-root metadata —
which may belong to a different server on the same gateway — and authenticates against the wrong
backend. - Serve the metadata where a path-issuer client looks for it. Per RFC 8414, for an issuer with a
path the client requests the insertion URLhttps://host/.well-known/oauth-authorization-server/<prefix>(the well-known segment goes before
the prefix), nothttps://host/<prefix>/.well-known/oauth-authorization-server. The app serves the
document at its own/.well-known/oauth-authorization-server(which APIM exposes at the path-append
URL). If your gateway routes the insertion URL elsewhere (e.g. to another API), add a small route
that forwards…/.well-known/oauth-authorization-server/<prefix>to this app's/.well-known/oauth-authorization-server. If your server is alone on its own host/origin, neither
issue arises — the bare-host issuer just works.
Verify all three resolve to your server before connecting a client:
PREFIX=zendesk-mcp ; HOST=https://your-gateway.example.com
curl -s "$HOST/$PREFIX/.well-known/oauth-protected-resource" # authorization_servers should end in /$PREFIX
curl -s "$HOST/.well-known/oauth-authorization-server/$PREFIX" # insertion path — must return YOUR metadata
curl -s "$HOST/$PREFIX/.well-known/oauth-authorization-server" # append path — same metadata
All should show issuer/endpoints under …/$PREFIX/…. A 404 on the insertion path is the classic
cause of a client failing client registration after discovery.
Step 4 — Continuous deployment (optional)
The workflows under .github/workflows/ build, test and deploy. deploy.yml
publishes to App Service on push to main. Before it works you must provide credentials — either:
- a publish profile: set repo secret
AZURE_WEBAPP_PUBLISH_PROFILEand variableAZURE_WEBAPP_NAME
(the App Service name); or - an
azure/loginstep with a federated (OIDC) service principal.
Without one of these the deploy step fails with No credentials found even though build and tests pass.
Step 5 — Connect Claude web
In Claude web: Settings → Connectors → Add custom connector, enterhttps://your-gateway.example.com/<route-prefix>, and Claude runs the OAuth flow against Entra ID and
connects.
Connecting a client
Claude Code — local stdio (Path 1)
claude mcp add zendesk -- docker run --rm -i --env-file /full/path/to/.env zendesk-mcp
claude mcp list # zendesk should show "connected"
Claude Code — hosted HTTP
# Path 2 (API key):
claude mcp add zendesk --transport http https://your-host/<prefix> --header "X-API-Key:<your key>"
# Path 3 (OAuth): add the URL, then run /mcp in Claude Code and choose Authenticate
claude mcp add zendesk --transport http https://your-gateway.example.com/<route-prefix>
Claude web (Path 3)
Settings → Connectors → Add custom connector → the server URL. See Step 5.
Any other MCP client
Point it at the stdio command (Path 1) or the HTTP URL (Paths 2/3). For HTTP+OAuth, the client needs to
support the MCP OAuth flow; for HTTP+API-key it just needs to send the X-API-Key header.
Once connected, try search_tickets with a query like group:"Dev Team" status:open.
How authentication works
Two separate layers — keep them apart:
- Talking to Zendesk. The server uses one Zendesk API token with an agent e-mail (HTTP Basic
auth,email/token:api_token). InSharedmode (the default, all three paths) every action is
attributed to the one shared service account inZENDESK_EMAIL. InMappedmode (Path 3 only)
the e-mail is chosen for each request from the signed-in person — see
Per-user Zendesk agents. - Talking to the server.
- stdio (Path 1): nothing to authenticate — you run the process.
- http, non-Production (Path 2): the
ApiKeyAuthMiddlewarechecks theX-API-Keyheader againstMCP_API_KEY. - http, Production (Path 3): the API-key middleware is disabled. The gateway validates a
Microsoft Entra ID JWT, and the server exposes an OAuth 2.1 bridge (Auth/OAuthEndpoints.cs):
it presents itself as the authorization server (metadata + dynamic client registration), and
bridges the flow to Entra, keeping two PKCE layers — one with the MCP client and an internal one
with Entra. Refresh grants are bridged the same way: the server forwards the client's refresh
token to Entra together with a managed-identity client assertion, so sessions renew without
re-prompting (this requiresoffline_accessinOAuth__Scopes— without it Entra never issues
a refresh token).
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Client error: Invalid OAuth error response… Unrecognized token < |
The OAuth/MCP request reached a backend returning an HTML error page (stopped/cold app, or wrong serviceUrl). |
Confirm the gateway's backend points at a running app; check the App Service is up. |
| Discovery resolves the wrong server's metadata | authorization_servers advertised as the bare host on a shared gateway. |
Set OAuth__ExternalBaseUrl + OAuth__RoutePrefix so the issuer carries the path; see discovery note. |
Client fails right after discovery (e.g. client_uri / metadata not found) |
Auth-server metadata not served at the RFC 8414 insertion URL. | Add the insertion-path route; verify with the three curls above. |
| Claude web silently never starts OAuth | 401 response missing CORS headers. | Ensure the policy's <on-error> block sets the CORS headers (it does by default). |
Client error: 404 Session not found (JSON-RPC -32001) |
The client is replaying an Mcp-Session-Id the server no longer holds. Stateful sessions live in App Service process memory, so they are lost on restart or scale-out and expire after the transport's IdleTimeout (2 hours by default). |
The HTTP transport now runs with Stateless = true, so no session id is issued or required. A client stuck on a cached id needs the connector removed and re-added once. |
| Users must re-authenticate roughly every hour | No refresh token issued (offline_access missing from the deployed OAuth__Scopes), or Entra rejects the refresh grant (AADSTS7000218) because it lacks a client assertion. |
Include offline_access in OAuth__Scopes and re-authenticate once; ensure the build sends the managed-identity client assertion on refresh. |
Deploy fails: No credentials found |
CD not wired. | Set AZURE_WEBAPP_PUBLISH_PROFILE + AZURE_WEBAPP_NAME, or add azure/login. |
| Startup warns Zendesk credentials are not fully configured | Missing Zendesk env vars. | Set ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_TOKEN. |
Someone gets access_denied at sign-in, or 403 … is not allowed to use this server |
Mapped mode is on and their sign-in address is not in ZENDESK_USER_MAPPINGS (or their token carries a different address from the one you mapped). |
Add the address shown in the server log's warning, then restart. |
| Server stops at startup: UserLoginMode 'Mapped' needs … | Mapped mode on stdio or non-Production HTTP, where there is no signed-in user. |
Use Path 3, or set ZENDESK_USER_LOGIN_MODE=Shared. |
Zendesk returns 401 for one person only |
In Mapped mode, their mapped Zendesk address is not an agent in the account. |
Map them to an existing agent. |
| Values look right but auth to Zendesk fails from Docker | .env saved with CRLF line endings leaking \r (the code trims, but double-check). |
Save .env with LF line endings. |
Security notes
- In
Sharedmode (the default) there is a single shared Zendesk account, so anyone who can reach the
server can act as that account. Keep the credentials in a secret store and keep the server
access-controlled. Mappedmode limits the server to the people you list, each acting as the agent you chose. The API
token itself can still act as any agent, so guard it just as closely.zendesk_requestcan call any endpoint, including destructive ones. It is unrestricted by default
because hosted access is gated by OAuth. To narrow it, restrict the allowed HTTP methods insrc/ZendeskMcp.Server/Tools/GenericTools.cs.- The write tools (
create_ticket,update_ticket,create_ticket_comment,delete_ticket) change
live Zendesk data — the server instructions ask the model to confirm before using them. - Never commit secrets.
.envis git-ignored; deployment secrets belong in your platform's config
store / Key Vault, and APIM named values for secrets should be Key Vault-backed.
Project structure & development
src/ZendeskMcp.Server/
Program.cs # host + dual-transport switch (stdio / http)
Auth/ # OAuth 2.1 bridge to Entra ID, API key middleware, per-user login gate
Zendesk/ # ZendeskClient, options, attachment validation (no host-internal deps)
Tools/ # the MCP tools
Prompts/ # analyze-ticket, draft-ticket-response
Resources/ # zendesk://knowledge-base
Dockerfile
apim-policies/ # API Management policy + notes
tests/ZendeskMcp.Tests/ # unit tests
The Zendesk/ folder is intentionally free of host-internal dependencies, so the Zendesk core stays
portable.
dotnet build ZendeskMcp.slnx
dotnet test ZendeskMcp.slnx
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi