@fruggr/zendesk-mcp-server 1.6.0 → 1.8.0

package/README.md

@@ -190,7 +190,9 @@ No API key needed. Each user authenticates via their browser on the first tool c
 1. Go to **Admin Center > Apps and integrations > APIs > OAuth Clients**
 2. Create a public client:
    - **Identifier**: `<your-subdomain>_zendesk` (or set `ZENDESK_OAUTH_CLIENT_ID`)
-   - **Redirect URL**: `http://localhost:3000/callback`
+   - **Redirect URL**: `http://localhost:27439/callback` (change the port to match
+     `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
+     accepts several redirect URLs, one per line)
 
 **Run:**
 
@@ -201,8 +203,22 @@ zendesk-mcp-server <your-subdomain>
 On the first tool call, the server starts the sign-in flow: it opens a browser
 window **and** returns a tool message containing the authorize URL. The call
 does not block waiting for sign-in — authenticate in the browser (or open the
-URL manually if it didn't open), then retry the request. Once authenticated, the
-token is cached in memory and subsequent calls succeed for the session.
+URL manually if it didn't open), then retry the request.
+
+Once authenticated, the token is **persisted to disk** (one owner-only `0600`
+file per subdomain in your OS config dir —
+`%APPDATA%\fruggr\zendesk-mcp-server\<subdomain>.json` on Windows,
+`${XDG_CONFIG_HOME:-~/.config}/fruggr/zendesk-mcp-server/<subdomain>.json`
+elsewhere; override the path with `ZENDESK_TOKEN_FILE`). It is reused across restarts, so you don't
+re-authenticate every time the MCP client respawns the server. If the Zendesk
+OAuth client has token expiration enabled, the stored refresh token is used to
+renew access silently; only an expired/invalid refresh token triggers a new
+browser sign-in.
+
+> **Port conflict?** If port `27439` is already in use the first tool call returns
+> a clear error telling you to set `ZENDESK_OAUTH_CALLBACK_PORT` (or
+> `--callback-port`) to a free port — remember to register the matching
+> `http://localhost:<port>/callback` redirect URL in your Zendesk OAuth client.
 
 ### Option B: API token
 
@@ -290,6 +306,7 @@ Options:
   --tool <name>           Filter by tool name (repeatable, forces --mode all)
   --read-only             Only expose read operations
   --log-level <level>     debug | info (default) | warn | error
+  --callback-port <port>  Local OAuth callback port (default 27439)
 ```
 
 `--namespace` and `--read-only` are applied before the proxies are registered, so they narrow the surface in every mode — in the default `namespace` mode, `--namespace help_center` registers a single proxy (`zendesk_help_center`) instead of three.
@@ -313,6 +330,8 @@ zendesk-mcp-server acme --tool get_ticket --tool search_tickets --tool get_curre
 |----------|----------|---------|-------------|
 | `ZENDESK_SUBDOMAIN` | yes (or CLI arg) | — | Zendesk subdomain (e.g., `acme` for acme.zendesk.com) |
 | `ZENDESK_OAUTH_CLIENT_ID` | no | `<subdomain>_zendesk` | OAuth client identifier |
+| `ZENDESK_OAUTH_CALLBACK_PORT` | no | `27439` | Local port for the OAuth browser callback (also `--callback-port`). Must match the redirect URL registered in Zendesk. |
+| `ZENDESK_TOKEN_FILE` | no | OS config dir | Path to the persisted OAuth token file (`0600`). |
 | `ZENDESK_EMAIL` | for API token auth | — | Agent email for Basic auth |
 | `ZENDESK_API_TOKEN` | for API token auth | — | Zendesk API token |
 | `LOG_LEVEL` | no | `info` | Log verbosity (`debug` surfaces the full OAuth flow trace) |
@@ -340,6 +359,22 @@ When the browser fails to open, look for the `oauth_browser_open_failed` event:
 it reports the underlying error, the platform, and which environment markers are
 present (no secrets, tokens, or env values are ever logged).
 
+### The OAuth callback port is already in use
+
+The sign-in flow runs a short-lived local server on port `27439` to receive the
+callback. If that port is taken, the first tool call fails with a message saying
+so (and logs `oauth_callback_listen_failed`). Pick a free port with
+`ZENDESK_OAUTH_CALLBACK_PORT=<port>` (or `--callback-port <port>`), and register
+the matching `http://localhost:<port>/callback` redirect URL in your Zendesk
+OAuth client.
+
+### I have to re-authenticate every time
+
+The OAuth token is persisted to an owner-only file in your OS config dir and
+reused across restarts, so this shouldn't happen. If it does, check that the file
+is writable (`ZENDESK_TOKEN_FILE` to relocate it) and look for
+`token_persist_failed` in the logs.
+
 Where each client writes the server's stderr:
 
 | Client | Log location |

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { release } from "node:os";
+import { homedir, release } from "node:os";
 import open from "open";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as z from "zod/v4";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as cheerio from "cheerio";
@@ -17,8 +19,6 @@ import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import remarkStringify from "remark-stringify";
 import { unified } from "unified";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/auth/api-token.ts
 /**
@@ -126,7 +126,6 @@ const getOAuthUrls = (subdomain) => ({
 });
 //#endregion
 //#region src/auth/browser-oauth.ts
-const DEFAULT_CALLBACK_PORT = 3e3;
 const AUTH_TIMEOUT_MS = 300 * 1e3;
 /** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
 const detectWsl = () => {
@@ -138,6 +137,16 @@ const detectWsl = () => {
 	}
 };
 /**
+* Build an actionable error for a callback port that's already taken. The raw
+* Node `EADDRINUSE` is opaque to both the user and the LLM; this spells out the
+* fix (set a free port + register the matching redirect URL in Zendesk). The
+* `(EADDRINUSE)` marker and `code` are kept for diagnostics/tests.
+*/
+const callbackPortInUseError = (port, cause) => Object.assign(/* @__PURE__ */ new Error(`Cannot start the Zendesk OAuth sign-in: local callback port ${port} is already in use by another process. Set ZENDESK_OAUTH_CALLBACK_PORT (or --callback-port) to a free port, then register http://localhost:<port>/callback as a redirect URL in your Zendesk OAuth client. (EADDRINUSE)`), {
+	code: "EADDRINUSE",
+	cause
+});
+/**
 * Escape a string for safe interpolation into HTML text/attribute context.
 * The local callback server echoes attacker-controllable values (the OAuth
 * `error_description` query param, token-exchange error bodies) back into the
@@ -221,7 +230,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				const tokenData = await tokenResponse.json();
 				logger.info("oauth_authenticated");
 				res.writeHead(200, { "Content-Type": "text/html" });
-				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to Claude Code.</p><script>window.close()<\/script></body></html>");
+				res.end("<html><body><h1>Authentication successful!</h1><p>You can close this tab and return to Claude Code.</p><p>This tab will auto-close in <span id=\"t\">10</span>s.</p><script>let n=10;const el=document.getElementById(\"t\");const i=setInterval(()=>{n--;el.textContent=n;if(n<=0){clearInterval(i);window.close();}},1000);<\/script></body></html>");
 				clearTimeout(authTimeout);
 				callbackServer.close();
 				resolveToken(tokenData);
@@ -233,12 +242,18 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				rejectToken(err);
 			}
 		});
+		const requestedPort = config.callbackPort ?? 27439;
 		const onStartError = (err) => {
 			clearTimeout(authTimeout);
-			rejectStarted(err);
+			const code = err.code;
+			logger.error("oauth_callback_listen_failed", {
+				port: requestedPort,
+				errorCode: code
+			});
+			rejectStarted(code === "EADDRINUSE" ? callbackPortInUseError(requestedPort, err) : err);
 		};
 		callbackServer.once("error", onStartError);
-		callbackServer.listen(config.callbackPort ?? DEFAULT_CALLBACK_PORT, () => {
+		callbackServer.listen(requestedPort, () => {
 			callbackServer.off("error", onStartError);
 			callbackServer.once("error", (err) => {
 				clearTimeout(authTimeout);
@@ -292,34 +307,199 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 		});
 	});
 };
+/**
+* Exchange a refresh token for a fresh access token (and a rotated refresh token)
+* without any browser interaction. Public PKCE clients send no `client_secret`.
+* Zendesk refresh tokens are single-use: the caller MUST persist the new
+* `refresh_token` from the response. Throws on a non-2xx (expired/invalid
+* refresh token) so the caller can fall back to the full browser flow.
+*/
+const refreshAccessToken = async (config, logger = silentLogger) => {
+	const { tokenUrl } = getOAuthUrls(config.subdomain);
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: config.refreshToken,
+		client_id: config.oauthClientId
+	});
+	const response = await fetch(tokenUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: body.toString()
+	});
+	logger.debug("oauth_token_refresh", { status: response.status });
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(`Token refresh failed (${response.status}): ${errorBody}`);
+	}
+	const tokenData = await response.json();
+	logger.info("oauth_token_refreshed");
+	return tokenData;
+};
+//#endregion
+//#region src/utils/package-info.ts
+const FALLBACK = {
+	name: "@fruggr/zendesk-mcp-server",
+	version: "0.0.0"
+};
+/**
+* Read `name`/`version` from the package's own package.json at runtime instead
+* of hardcoding them. Walks up from this module to the nearest package.json,
+* which resolves correctly both when bundled (`dist/index.js` → repo root) and
+* from source/tests (`src/` has no package.json, so the root is found). Reading
+* at runtime (not inlining at build) matters because semantic-release bumps the
+* version into package.json before publishing, after the build step.
+*/
+let cached;
+const readPackageInfo = () => {
+	if (cached) return cached;
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 8; depth++) {
+		try {
+			const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (raw && typeof raw === "object") {
+				const pkg = raw;
+				if (typeof pkg.name === "string" && typeof pkg.version === "string") {
+					cached = {
+						name: pkg.name,
+						version: pkg.version
+					};
+					return cached;
+				}
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	cached = FALLBACK;
+	return cached;
+};
+//#endregion
+//#region src/auth/token-persistence.ts
+const isWindows = process.platform === "win32";
+/**
+* Config-dir segments derived from the *scoped* package name
+* (`@fruggr/zendesk-mcp-server` → `fruggr` + `zendesk-mcp-server`) so the path is
+* vendor-namespaced and can't collide with another `zendesk-mcp-server`.
+*/
+const appDirSegments = () => {
+	const { name } = readPackageInfo();
+	const scoped = /^@([^/]+)\/(.+)$/.exec(name);
+	return scoped?.[1] && scoped[2] ? [scoped[1], scoped[2]] : [name];
+};
+const configDir = () => {
+	const segments = appDirSegments();
+	if (isWindows) return join(process.env["APPDATA"] ?? join(homedir(), "AppData", "Roaming"), ...segments);
+	return join(process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), ...segments);
+};
+const safeName = (subdomain) => subdomain.replace(/[^a-z0-9-]/gi, "_");
+/**
+* Path to the token file for a subdomain. Each subdomain gets its **own** file
+* (`<subdomain>.json`, a single record) so concurrent processes for different
+* subdomains never read-modify-write a shared file — no merge, no clobber.
+* `ZENDESK_TOKEN_FILE` overrides with an explicit path (a single file; use the
+* default layout for multi-subdomain installs).
+*/
+const resolveTokenPath = (subdomain) => {
+	const override = process.env["ZENDESK_TOKEN_FILE"];
+	if (override) return override;
+	return join(configDir(), `${safeName(subdomain)}.json`);
+};
+const writeFileAtomic = (path, record) => {
+	const dir = dirname(path);
+	mkdirSync(dir, { recursive: true });
+	const tmp = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(record, null, 2), "utf8");
+	if (!isWindows) chmodSync(tmp, 384);
+	renameSync(tmp, path);
+	if (!isWindows) try {
+		chmodSync(dir, 448);
+	} catch {}
+};
+const loadToken = (path) => {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (raw && typeof raw === "object" && typeof raw.accessToken === "string") return raw;
+	} catch {}
+};
+const saveToken = (path, record, logger = silentLogger) => {
+	try {
+		writeFileAtomic(path, record);
+		logger.debug("token_persisted");
+	} catch (err) {
+		logger.warn("token_persist_failed", { error: err instanceof Error ? err.message : String(err) });
+	}
+};
+const clearToken = (path, logger = silentLogger) => {
+	try {
+		rmSync(path, { force: true });
+		logger.debug("token_cleared");
+	} catch (err) {
+		logger.warn("token_clear_failed", { error: err instanceof Error ? err.message : String(err) });
+	}
+};
 //#endregion
 //#region src/auth/token-store.ts
+const EXPIRY_SKEW_MS = 6e4;
 const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */ new Error("Zendesk authentication required. A browser window should have opened for you to sign in. If it did not, open this URL in your browser, then retry your request:\n" + authorizeUrl), {
 	name: "AuthRequiredError",
 	authorizeUrl
 });
+const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
 const createTokenStore = (config, logger = silentLogger) => {
-	let token;
+	const tokenPath = resolveTokenPath(config.subdomain);
+	let token = loadToken(tokenPath);
+	if (token) logger.debug("oauth_token_loaded_from_disk");
 	let authorizeUrl;
 	let starting;
+	let refreshing;
+	const persist = (t) => saveToken(tokenPath, t, logger);
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
 			refreshToken
 		};
+		persist(token);
+	};
+	const isExpired = (t) => typeof t.expiresAt === "number" && Date.now() >= t.expiresAt - EXPIRY_SKEW_MS;
+	const tryRefresh = async (current) => {
+		if (!current.refreshToken) return void 0;
+		try {
+			const result = await refreshAccessToken({
+				subdomain: config.subdomain,
+				oauthClientId: config.oauthClientId,
+				refreshToken: current.refreshToken
+			}, logger);
+			token = {
+				accessToken: result.access_token,
+				refreshToken: result.refresh_token ?? current.refreshToken,
+				expiresAt: expiryFrom(result.expires_in)
+			};
+			persist(token);
+			logger.info("oauth_token_refreshed_cached");
+			return token.accessToken;
+		} catch (err) {
+			logger.warn("oauth_token_refresh_failed", { error: err instanceof Error ? err.message : String(err) });
+			token = void 0;
+			clearToken(tokenPath, logger);
+			return;
+		}
 	};
 	const beginAuth = () => {
 		logger.info("oauth_auth_start");
 		return startBrowserAuth({
 			subdomain: config.subdomain,
-			oauthClientId: config.oauthClientId
+			oauthClientId: config.oauthClientId,
+			callbackPort: config.callbackPort
 		}, logger).then((started) => {
 			authorizeUrl = started.authorizeUrl;
 			started.tokenPromise.then((result) => {
 				token = {
 					accessToken: result.access_token,
-					refreshToken: result.refresh_token
+					refreshToken: result.refresh_token,
+					expiresAt: expiryFrom(result.expires_in)
 				};
+				persist(token);
 				logger.info("oauth_token_cached");
 			}).catch((err) => {
 				logger.warn("oauth_auth_failed", { error: err instanceof Error ? err.message : String(err) });
@@ -334,16 +514,38 @@ const createTokenStore = (config, logger = silentLogger) => {
 		});
 	};
 	const getToken = async () => {
-		if (token) {
+		if (token && !isExpired(token)) {
 			logger.debug("oauth_token_cache_hit");
 			return token.accessToken;
 		}
+		if (token?.refreshToken) {
+			if (!refreshing) refreshing = tryRefresh(token).finally(() => {
+				refreshing = void 0;
+			});
+			const refreshed = await refreshing;
+			if (refreshed) return refreshed;
+		}
 		if (!starting) starting = beginAuth();
 		throw createAuthRequiredError(authorizeUrl ?? await starting);
 	};
+	const invalidate = () => {
+		if (token?.refreshToken) {
+			token = {
+				accessToken: token.accessToken,
+				refreshToken: token.refreshToken,
+				expiresAt: 0
+			};
+			persist(token);
+		} else {
+			token = void 0;
+			clearToken(tokenPath, logger);
+		}
+		logger.info("oauth_token_invalidated");
+	};
 	return {
 		getToken,
-		setToken
+		setToken,
+		invalidate
 	};
 };
 //#endregion
@@ -373,7 +575,8 @@ const ConfigSchema = z.object({
 	mode: ToolMode,
 	readOnly: z.boolean(),
 	namespaces: z.array(Namespace).optional(),
-	tools: z.array(z.string()).optional()
+	tools: z.array(z.string()).optional(),
+	callbackPort: z.number().int().min(1).max(65535).optional()
 });
 const parseCliArgs = (args) => {
 	const result = {};
@@ -397,6 +600,9 @@ const parseCliArgs = (args) => {
 		} else if (arg === "--log-level" && next) {
 			result.logLevel = next;
 			i++;
+		} else if (arg === "--callback-port" && next) {
+			result.callbackPort = Number(next);
+			i++;
 		} else if (!arg.startsWith("-") && positionalIndex === 0) {
 			result.subdomain = arg;
 			positionalIndex++;
@@ -409,6 +615,8 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	const subdomain = cli.subdomain ?? process.env["ZENDESK_SUBDOMAIN"] ?? "";
 	const oauthClientId = process.env["ZENDESK_OAUTH_CLIENT_ID"] ?? (subdomain ? `${subdomain}_zendesk` : "");
 	const mode = cli.tools?.length ? "all" : cli.mode ?? "namespace";
+	const envCallbackPort = process.env["ZENDESK_OAUTH_CALLBACK_PORT"];
+	const callbackPort = cli.callbackPort ?? (envCallbackPort ? Number(envCallbackPort) : void 0);
 	return ConfigSchema.parse({
 		subdomain,
 		oauthClientId,
@@ -418,27 +626,11 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		mode,
 		readOnly: cli.readOnly ?? false,
 		namespaces: cli.namespaces,
-		tools: cli.tools
+		tools: cli.tools,
+		callbackPort
 	});
 };
 //#endregion
-//#region src/routing/registry.ts
-const filterTools = (allTools, options) => allTools.filter((tool) => {
-	if (options.readOnly && !tool.readOnly) return false;
-	if (options.namespaces?.length && !options.namespaces.includes(tool.namespace)) return false;
-	if (options.tools?.length && !options.tools.includes(tool.name)) return false;
-	return true;
-});
-const groupByNamespace = (tools) => {
-	const grouped = /* @__PURE__ */ new Map();
-	for (const tool of tools) {
-		const existing = grouped.get(tool.namespace) ?? [];
-		existing.push(tool);
-		grouped.set(tool.namespace, existing);
-	}
-	return grouped;
-};
-//#endregion
 //#region src/client/zendesk-api.ts
 var ZendeskApiError = class ZendeskApiError extends Error {
 	status;
@@ -548,6 +740,23 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 	return response.json();
 };
 //#endregion
+//#region src/routing/registry.ts
+const filterTools = (allTools, options) => allTools.filter((tool) => {
+	if (options.readOnly && !tool.readOnly) return false;
+	if (options.namespaces?.length && !options.namespaces.includes(tool.namespace)) return false;
+	if (options.tools?.length && !options.tools.includes(tool.name)) return false;
+	return true;
+});
+const groupByNamespace = (tools) => {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const tool of tools) {
+		const existing = grouped.get(tool.namespace) ?? [];
+		existing.push(tool);
+		grouped.set(tool.namespace, existing);
+	}
+	return grouped;
+};
+//#endregion
 //#region src/utils/article-sections.ts
 const HEADING_LEVELS = new Set([
 	"h1",
@@ -1981,46 +2190,21 @@ const createAllTools = (ctx) => [
 	...createUserTools(ctx)
 ];
 //#endregion
-//#region src/utils/package-info.ts
-const FALLBACK = {
-	name: "@fruggr/zendesk-mcp-server",
-	version: "0.0.0"
-};
+//#region src/server.ts
 /**
-* Read `name`/`version` from the package's own package.json at runtime instead
-* of hardcoding them. Walks up from this module to the nearest package.json,
-* which resolves correctly both when bundled (`dist/index.js` → repo root) and
-* from source/tests (`src/` has no package.json, so the root is found). Reading
-* at runtime (not inlining at build) matters because semantic-release bumps the
-* version into package.json before publishing, after the build step.
+* Invoke a tool handler, notifying `onUnauthorized` when Zendesk rejects the
+* token (401). This lets the OAuth store drop the dead token so the next call
+* refreshes/re-authenticates instead of replaying a revoked token. A no-op
+* callback (API-token mode) leaves behavior unchanged.
 */
-let cached;
-const readPackageInfo = () => {
-	if (cached) return cached;
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (let depth = 0; depth < 8; depth++) {
-		try {
-			const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
-			if (raw && typeof raw === "object") {
-				const pkg = raw;
-				if (typeof pkg.name === "string" && typeof pkg.version === "string") {
-					cached = {
-						name: pkg.name,
-						version: pkg.version
-					};
-					return cached;
-				}
-			}
-		} catch {}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+const runHandler = async (def, params, onUnauthorized) => {
+	try {
+		return await def.handler(params);
+	} catch (err) {
+		if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
+		throw err;
 	}
-	cached = FALLBACK;
-	return cached;
 };
-//#endregion
-//#region src/server.ts
 const NAMESPACE_LABELS = {
 	tickets: {
 		toolName: "zendesk_tickets",
@@ -2047,7 +2231,7 @@ const aggregateAnnotations = (tools) => ({
 	idempotentHint: tools.every((t) => t.annotations.idempotentHint),
 	openWorldHint: true
 });
-const registerProxyTool = (server, toolName, title, tools, handlerMap, readOnlyMode) => {
+const registerProxyTool = (server, toolName, title, tools, handlerMap, readOnlyMode, onUnauthorized) => {
 	const operationNames = tools.map((t) => t.name);
 	const operationList = buildOperationList(tools);
 	const annotations = aggregateAnnotations(tools);
@@ -2066,11 +2250,10 @@ const registerProxyTool = (server, toolName, title, tools, handlerMap, readOnlyM
 			type: "text",
 			text: `Unknown operation "${operation}". Available: ${operationNames.join(", ")}`
 		}] };
-		const validated = def.inputSchema.parse(params);
-		return def.handler(validated);
+		return runHandler(def, def.inputSchema.parse(params), onUnauthorized);
 	});
 };
-const createMcpServer = (config, getToken, logger = silentLogger) => {
+const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
 	const pkg = readPackageInfo();
 	const server = new McpServer({
 		name: pkg.name,
@@ -2094,18 +2277,18 @@ const createMcpServer = (config, getToken, logger = silentLogger) => {
 				description: tool.description,
 				inputSchema: tool.inputSchema,
 				annotations: tool.annotations
-			}, async (params) => tool.handler(params));
+			}, async (params) => runHandler(tool, params, onUnauthorized));
 			break;
 		case "namespace": {
 			const grouped = groupByNamespace(filteredTools);
 			for (const [namespace, tools] of grouped) {
 				const label = NAMESPACE_LABELS[namespace];
-				if (label) registerProxyTool(server, label.toolName, label.title, tools, handlerMap, config.readOnly);
+				if (label) registerProxyTool(server, label.toolName, label.title, tools, handlerMap, config.readOnly, onUnauthorized);
 			}
 			break;
 		}
 		case "single":
-			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, handlerMap, config.readOnly);
+			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, handlerMap, config.readOnly, onUnauthorized);
 			break;
 	}
 	logger.info("tools_registered", {
@@ -2130,10 +2313,14 @@ const main = async () => {
 		const staticToken = buildBasicAuthHeader(config.zendeskEmail, config.zendeskApiToken);
 		const getToken = () => staticToken;
 		await startStdioTransport(createMcpServer(config, getToken, logger), logger);
-	} else await startStdioTransport(createMcpServer(config, createTokenStore({
-		subdomain: config.subdomain,
-		oauthClientId: config.oauthClientId
-	}, logger).getToken, logger), logger);
+	} else {
+		const tokenStore = createTokenStore({
+			subdomain: config.subdomain,
+			oauthClientId: config.oauthClientId,
+			callbackPort: config.callbackPort
+		}, logger);
+		await startStdioTransport(createMcpServer(config, tokenStore.getToken, logger, tokenStore.invalidate), logger);
+	}
 };
 main().catch((error) => {
 	console.error("Fatal error:", error);