Help Desk

${escape(ctx.clientName)} wants to reach your queue${ctx.scopes.length ? ` (${escape(ctx.scopes.join(", "))})` : ""}.

${escape(ctx.error)}

Desk key

}) => fields.deskKey === "dk-7f3a" ? { ok: true as const, sub: "agent-nour" } : { ok: false as const, message: "Unknown desk key " }, }, }; ``` ```ts help-desk.app.ts import { App, Tool, ToolContext } from "@frontmcp/sdk"; @Tool({ name: "whoami", description: "Say who the server thinks is calling", inputSchema: {} }) export class WhoAmI extends ToolContext { async execute() { return { sub: this.auth.user.sub }; } } @App({ id: "help-desk", name: "Help Desk", tools: [WhoAmI] }) export class HelpDesk {} ``` ```ts render.test.ts import { test, expect } from "@frontmcp/testing"; import { OAuthClient } from "./oauth-client"; import { config } from "./server"; test("the sign-in page is yours", async () => { const client = await OAuthClient.for(config); await client.register(); const { status, page, pendingAuthId } = await client.authorize({ scope: "tickets:read" }); expect(status).toBe(200); expect(page).toMatch(/^/); expect(page).toContain("Help Desk sign-in"); expect(page).toContain(`wants to reach your queue (tickets:read)`); expect(page).toContain('

'); expect(pendingAuthId).toMatch(/^[0-9a-f-]{36}$/); }); test("it's sent with the built-in pages' headers, but no Content-Security-Policy", async () => { const client = await OAuthClient.for(config); await client.register(); const response = await client.send(`/oauth/authorize?${new URLSearchParams({ response_type: "code", client_id: client.clientId, redirect_uri: "http://localhost:3000/callback", code_challenge: "x".repeat(43) })}`); expect(response.headers.get("content-security-policy")).toBeNull(); expect(response.headers.get("x-frame-options")).toBe("DENY"); expect(response.headers.get("referrer-policy")).toBe("same-origin"); expect(response.headers.get("cache-control")).toBe("no-store"); }); test("a refused sign-in renders it again with the error", async () => { const client = await OAuthClient.for(config); await client.register(); const { pendingAuthId } = await client.authorize(); const { page } = await client.submit({ pending_auth_id: pendingAuthId!, deskKey: "nope" }); expect(page).toContain('

Unknown desk key <try again>

'); }); test("without extras, /oauth/ui/extra is a 404", async () => { const client = await OAuthClient.for(config); const response = await client.send("/oauth/ui/extra", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ action: "teams:add" }) }); expect(response.status).toBe(404); expect(await response.json()).toEqual({ ok: false, error: "No extras are configured." }); }); test("the form signs the user in", async () => { const client = await OAuthClient.for(config); const { access_token } = await client.signIn({ deskKey: "dk-7f3a" }); expect((await client.callTool(access_token, "whoami")).body.result.structuredContent).toEqual({ sub: "agent-nour" }); }); ``` ```ts oauth-client.ts hidden import { FrontMcpInstance } from "@frontmcp/sdk"; type Config = Parameters[0]; type Handler = (request: Request) => Promise; export const SERVER = "https://desk.example.com"; export const REDIRECT_URI = "http://localhost:3000/callback"; /** An MCP client's side of local-mode OAuth, and the user's browser: one request per step. */ export class OAuthClient { clientId = ""; /** PKCE: the client keeps this secret and only sends its SHA-256 to /oauth/authorize. */ readonly verifier = "a-random-string-of-43-to-128-characters-0123456789"; /** The browser's cookies for the server: /oauth/authorize sets one, and the form must send it back. */ readonly cookies = new Map(); private constructor(private readonly server: Handler) {} static async for(config: Config) { return new OAuthClient((await FrontMcpInstance.createFetchHandler(config)) as Handler); } async send(path: string, init: RequestInit = {}) { const headers = new Headers(init.headers); if (this.cookies.size) headers.set("cookie", [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; ")); const response = await this.server(new Request(SERVER + path, { redirect: "manual", ...init, headers })); for (const cookie of response.headers.getSetCookie()) { const [pair] = cookie.split(";"); const name = pair.slice(0, pair.indexOf("=")); const value = pair.slice(pair.indexOf("=") + 1); if (value) this.cookies.set(name, value); else this.cookies.delete(name); } return response; } /** 1. Register (dynamic client registration). */ async register(metadata: Record = {}) { const response = await this.send("/oauth/register", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ client_name: "Desk CLI", redirect_uris: [REDIRECT_URI], grant_types: ["authorization_code", "refresh_token"], ...metadata }), }); const body = await response.json(); if (response.status === 201) this.clientId = body.client_id; return { status: response.status, body }; } /** 2. Open the sign-in page, and find the pending_auth_id its form carries. */ async authorize(params: Record = {}) { const query = new URLSearchParams({ response_type: "code", client_id: this.clientId, redirect_uri: REDIRECT_URI, state: "xyz", code_challenge: await sha256(this.verifier), code_challenge_method: "S256", ...params, }); const response = await this.send(`/oauth/authorize?${query}`); const page = await response.text(); return { status: response.status, page, pendingAuthId: page.match(/name="pending_auth_id" value="([^"]+)"/)?.[1] }; } /** 3. Submit the sign-in form, as the user's browser does: a POST, with the cookie. */ async submit(fields: Record) { const response = await this.send("/oauth/callback", { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(fields), }); const location = response.headers.get("location"); return { status: response.status, page: await response.text(), location, code: location ? new URL(location).searchParams.get("code") : null }; } /** 4. Trade the code and the PKCE verifier for tokens. */ exchange(code: string) { return this.token({ grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI, client_id: this.clientId, code_verifier: this.verifier }); } refresh(refreshToken: string) { return this.token({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: this.clientId }); } async token(form: Record) { const response = await this.send("/oauth/token", { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(form) }); return { status: response.status, body: await response.json() }; } /** Steps 1 to 4, for tests that only need a token. */ async signIn(fields: Record, params: Record = {}) { if (!this.clientId) await this.register(); const { pendingAuthId } = await this.authorize(params); const { code } = await this.submit({ pending_auth_id: pendingAuthId!, ...fields }); return (await this.exchange(code!)).body; } /** An MCP tools/call, with or without an access token. */ async callTool(accessToken: string | undefined, name: string, args: Record = {}) { const response = await this.send("/", { method: "POST", headers: { "content-type": "application/json", "mcp-protocol-version": "2026-07-28", "mcp-method": "tools/call", "mcp-name": name, ...(accessToken ? { authorization: `Bearer ${accessToken}` } : {}), }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args, _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } } }), }); return { status: response.status, headers: response.headers, body: await response.json() }; } } /** The claims of a JWT, without checking it. */ export function claimsOf(jwt: string) { return JSON.parse(atob(jwt.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"))); } async function sha256(text: string) { const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))); return btoa(String.fromCharCode(...digest)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); } ``` ### Asking which tools a client may use With a consent screen, the user decides which tools this client gets. Here `list_tickets` is always allowed, and the user picks among the rest. ```ts server.ts active import { Billing, HelpDesk } from "./apps"; export const config = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDesk, Billing], auth: { mode: "local" as const, consent: { enabled: true, excludedTools: ["list_tickets"], customMessage: "Choose what the assistant may do for you.", }, }, }; ``` ```ts apps.ts import { App, Tool, ToolContext, z } from "@frontmcp/sdk"; @Tool({ name: "list_tickets", description: "List open tickets", inputSchema: {} }) class ListTickets extends ToolContext { async execute() { return { tickets: ["T-1", "T-2"] }; } } @Tool({ name: "close_ticket", description: "Close a ticket", inputSchema: { id: z.string() } }) class CloseTicket extends ToolContext { async execute({ id }: { id: string }) { return { id, status: "closed" }; } } @Tool({ name: "refund_invoice", description: "Refund an invoice", inputSchema: { id: z.string() } }) class RefundInvoice extends ToolContext { async execute({ id }: { id: string }) { return { id, refunded: true }; } } @App({ id: "help-desk", name: "Help Desk", tools: [ListTickets, CloseTicket] }) export class HelpDesk {} @App({ id: "billing", name: "Billing", tools: [RefundInvoice] }) export class Billing {} ``` ```ts consent.test.ts import { test, expect } from "@frontmcp/testing"; import { OAuthClient, claimsOf } from "./oauth-client"; import { config } from "./server"; /** The CSRF token on the consent screen, which the choice must send back. */ const csrfOf = (page: string) => page.match(/name="csrf" value="([^"]+)"/)![1]; /** Signs in and returns the consent screen. */ async function consentScreen(client: OAuthClient, fields: Record = { email: "nour@example.com" }) { if (!client.clientId) await client.register(); const { pendingAuthId } = await client.authorize(); const screen = await client.submit({ pending_auth_id: pendingAuthId!, ...fields }); /** Sends the user's choice: one tool ticked, or none. */ const choose = (tool?: string) => client.submit({ pending_auth_id: pendingAuthId!, csrf: csrfOf(screen.page), consent_submitted: "1", ...(tool ? { tools: tool } : {}) }); return { ...screen, pendingAuthId: pendingAuthId!, choose }; } test("after sign-in, the user sees a consent screen instead of a redirect", async () => { const { status, location, page, pendingAuthId } = await consentScreen(await OAuthClient.for(config)); expect(status).toBe(200); expect(location).toBeNull(); expect(page).toContain("Choose what the assistant may do for you."); expect(page).toContain("Signed in as:"); expect(page).toContain(''); expect(page).toContain(``); expect(page).toMatch(//); expect(page).not.toContain('name="email"'); // the sign-in stays on the server expect(page).toContain('name="tools" value="close_ticket"'); expect(page).toContain('name="tools" value="refund_invoice"'); expect(page).not.toContain('value="list_tickets"'); // excluded: always allowed }); test("the token only reaches the tools the user picked", async () => { const client = await OAuthClient.for(config); const { code } = await (await consentScreen(client)).choose("close_ticket"); const { access_token } = (await client.exchange(code!)).body; expect(claimsOf(access_token).consent).toEqual({ enabled: true, selectedTools: ["close_ticket", "list_tickets"] }); expect((await client.callTool(access_token, "list_tickets")).body.result.isError).toBeUndefined(); expect((await client.callTool(access_token, "close_ticket", { id: "T-1" })).body.result.structuredContent).toEqual({ id: "T-1", status: "closed" }); const refused = (await client.callTool(access_token, "refund_invoice", { id: "INV-7" })).body.result; expect(refused).toMatchObject({ isError: true, _meta: { code: "TOOL_NOT_CONSENTED" } }); expect(refused.content[0].text).toBe('Tool "billing:refund_invoice" was not consented for this session. Re-authorize and select it to enable access.'); // tools/list isn't filtered const list = await client.send("/", { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${access_token}`, "mcp-protocol-version": "2026-07-28", "mcp-method": "tools/list" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: { _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } } }), }); expect((await list.json()).result.tools.map((tool: { name: string }) => tool.name)).toEqual(["close_ticket", "list_tickets", "refund_invoice"]); }); test("a choice sent without the screen's CSRF token is refused", async () => { const client = await OAuthClient.for(config); const { pendingAuthId } = await consentScreen(client); const forged = await client.submit({ pending_auth_id: pendingAuthId, consent_submitted: "1", tools: "refund_invoice" }); expect(forged.status).toBe(400); expect(forged.page).toContain("Invalid or missing CSRF token"); }); test("the screen's options", async () => { const client = await OAuthClient.for({ ...config, auth: { mode: "local" as const, consent: { enabled: true, groupByApp: false, showDescriptions: false, allowSelectAll: false, requireSelection: false, defaultSelectedTools: ["list_tickets"] } }, }); const screen = await consentScreen(client); expect(screen.page).toContain(`Choose which tools ${client.clientId} can access. You can change this later.`); expect(screen.page).toContain('name="tools" value="list_tickets" class="mt-0.5 w-5 h-5 rounded border-gray-300" checked>'); expect(screen.page).toContain('name="tools" value="close_ticket" class="mt-0.5 w-5 h-5 rounded border-gray-300">'); // not checked for (const gone of ["Select all tools", "Toggle All", "Close a ticket"]) expect(screen.page).not.toContain(gone); // requireSelection: false accepts an empty choice: no tool at all const { code } = await screen.choose(); const { access_token } = (await client.exchange(code!)).body; expect(claimsOf(access_token).consent).toEqual({ enabled: true, selectedTools: [] }); expect((await client.callTool(access_token, "list_tickets")).body.result._meta.code).toBe("TOOL_NOT_CONSENTED"); }); test("with authenticate, the sign-in is checked once, and the form doesn't carry it", async () => { const keys: string[] = []; const client = await OAuthClient.for({ ...config, auth: { mode: "local" as const, consent: { enabled: true }, login: { fields: { deskKey: { type: "password" as const, label: "Desk key" } } }, authenticate: async ({ fields }: { fields: Record }) => { keys.push(fields.deskKey); return fields.deskKey === "dk-7f3a" ? { ok: true as const, sub: "agent-nour" } : { ok: false as const, message: "Unknown desk key." }; }, }, }); const screen = await consentScreen(client, { deskKey: "dk-7f3a" }); expect(screen.page).not.toContain("dk-7f3a"); const { code } = await screen.choose("close_ticket"); expect(claimsOf((await client.exchange(code!)).body.access_token).sub).toBe("agent-nour"); expect(keys).toEqual(["dk-7f3a"]); }); test("an empty choice shows the screen again", async () => { const empty = await (await consentScreen(await OAuthClient.for(config))).choose(); expect(empty.status).toBe(200); expect(empty.page).toContain("Please select at least one tool to continue."); }); test("a tool that wasn't offered is refused", async () => { const forged = await (await consentScreen(await OAuthClient.for(config))).choose("delete_everything"); expect(forged.status).toBe(400); expect(forged.page).toContain("Invalid tool selection. Please restart authorization and choose from the available tools."); }); test("the choice is remembered for the same user and client", async () => { const client = await OAuthClient.for(config); await (await consentScreen(client)).choose("close_ticket"); const nour = await consentScreen(client); expect(nour.status).toBe(302); // no screen this time expect(claimsOf((await client.exchange(nour.code!)).body.access_token).consent.selectedTools).toEqual(["close_ticket", "list_tickets"]); const sam = await consentScreen(client, { email: "sam@example.com" }); expect(sam.status).toBe(200); // a new user sees the screen }); ``` ```ts oauth-client.ts hidden import { FrontMcpInstance } from "@frontmcp/sdk"; type Config = Parameters[0]; type Handler = (request: Request) => Promise; export const SERVER = "https://desk.example.com"; export const REDIRECT_URI = "http://localhost:3000/callback"; /** An MCP client's side of local-mode OAuth, and the user's browser: one request per step. */ export class OAuthClient { clientId = ""; /** PKCE: the client keeps this secret and only sends its SHA-256 to /oauth/authorize. */ readonly verifier = "a-random-string-of-43-to-128-characters-0123456789"; /** The browser's cookies for the server: /oauth/authorize sets one, and the form must send it back. */ readonly cookies = new Map(); private constructor(private readonly server: Handler) {} static async for(config: Config) { return new OAuthClient((await FrontMcpInstance.createFetchHandler(config)) as Handler); } async send(path: string, init: RequestInit = {}) { const headers = new Headers(init.headers); if (this.cookies.size) headers.set("cookie", [...this.cookies].map(([name, value]) => `${name}=${value}`).join("; ")); const response = await this.server(new Request(SERVER + path, { redirect: "manual", ...init, headers })); for (const cookie of response.headers.getSetCookie()) { const [pair] = cookie.split(";"); const name = pair.slice(0, pair.indexOf("=")); const value = pair.slice(pair.indexOf("=") + 1); if (value) this.cookies.set(name, value); else this.cookies.delete(name); } return response; } /** 1. Register (dynamic client registration). */ async register(metadata: Record = {}) { const response = await this.send("/oauth/register", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ client_name: "Desk CLI", redirect_uris: [REDIRECT_URI], grant_types: ["authorization_code", "refresh_token"], ...metadata }), }); const body = await response.json(); if (response.status === 201) this.clientId = body.client_id; return { status: response.status, body }; } /** 2. Open the sign-in page, and find the pending_auth_id its form carries. */ async authorize(params: Record = {}) { const query = new URLSearchParams({ response_type: "code", client_id: this.clientId, redirect_uri: REDIRECT_URI, state: "xyz", code_challenge: await sha256(this.verifier), code_challenge_method: "S256", ...params, }); const response = await this.send(`/oauth/authorize?${query}`); const page = await response.text(); return { status: response.status, page, pendingAuthId: page.match(/name="pending_auth_id" value="([^"]+)"/)?.[1] }; } /** 3. Submit the sign-in form, as the user's browser does: a POST, with the cookie. */ async submit(fields: Record) { const response = await this.send("/oauth/callback", { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(fields), }); const location = response.headers.get("location"); return { status: response.status, page: await response.text(), location, code: location ? new URL(location).searchParams.get("code") : null }; } /** 4. Trade the code and the PKCE verifier for tokens. */ exchange(code: string) { return this.token({ grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI, client_id: this.clientId, code_verifier: this.verifier }); } refresh(refreshToken: string) { return this.token({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: this.clientId }); } async token(form: Record) { const response = await this.send("/oauth/token", { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(form) }); return { status: response.status, body: await response.json() }; } /** Steps 1 to 4, for tests that only need a token. */ async signIn(fields: Record, params: Record = {}) { if (!this.clientId) await this.register(); const { pendingAuthId } = await this.authorize(params); const { code } = await this.submit({ pending_auth_id: pendingAuthId!, ...fields }); return (await this.exchange(code!)).body; } /** An MCP tools/call, with or without an access token. */ async callTool(accessToken: string | undefined, name: string, args: Record = {}) { const response = await this.send("/", { method: "POST", headers: { "content-type": "application/json", "mcp-protocol-version": "2026-07-28", "mcp-method": "tools/call", "mcp-name": name, ...(accessToken ? { authorization: `Bearer ${accessToken}` } : {}), }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args, _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } } }), }); return { status: response.status, headers: response.headers, body: await response.json() }; } } /** The claims of a JWT, without checking it. */ export function claimsOf(jwt: string) { return JSON.parse(atob(jwt.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"))); } async function sha256(text: string) { const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))); return btoa(String.fromCharCode(...digest)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); } ``` The consent form sends the choice as one `tools` parameter per ticked tool, with the sign-in's `pending_auth_id`, the screen's `csrf` and `consent_submitted=1`, and the browser sends the sign-in cookie with it. A `TOOL_NOT_CONSENTED` result tells the model which tool it was refused; the user gets it by signing in again and ticking it. [Progressive auth](https://frontmcp.dev/reference/auth/progressive) covers asking for more later. ### Using a React component `auth.ui` needs files on disk and a browser to render them, so it doesn't run in the Playground. This page replaces the sign-in page: ```tsx auth/login.tsx import React from "react"; import { useAuthFlow } from "@frontmcp/ui/auth"; export default function LoginPage() { const { clientName, scopes, error } = useAuthFlow(); return (

Sign in to Help Desk

{clientName} asks for {scopes.join(", ") || "access to your queue"}.

{error &&

{error}

} {/* around this component already renders the with pending_auth_id and csrf */} Desk key

); } ``` ```ts main.ts import { FrontMcp } from "@frontmcp/sdk"; import { HelpDesk } from "./help-desk.app"; import { checkDeskKey } from "./agents"; @FrontMcp({ info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDesk], auth: { mode: "local", ui: { login: "./auth/login.tsx" }, authenticate: checkDeskKey, }, }) export default class Server {} ``` The sign-in page is then an empty `

`, the state in `window.__FRONTMCP_AUTH__`, and a module script with your component, served with the headers listed in [`auth.ui`](#authui-react-pages). React and `@frontmcp/ui/auth` load from `esm.sh`, so the user's browser needs to reach it. This was checked in Node, with a CommonJS build and, on FrontMCP 1.9.2, in an ES module project (`"type": "module"`), which before 1.9.0 fell back to the built-in page: see [Troubleshooting](#the-built-in-page-shows-instead-of-your-authui-component). --- ## Troubleshooting ### `Email is required` after adding `login.fields` Your fields replaced the email field, but without `authenticate` FrontMCP still asks for one. Add an [`authenticate`](https://frontmcp.dev/reference/auth/local#checking-users-yourself) that checks your fields. ### Every user signs in as the same user `authenticate` returns `{ ok: true }` without a `sub`, and there's no `login.subject`, so everyone gets the `sub` of `anonymousSubject`. Return the user's id as `sub`. ### `This sign-in was started in another browser, or at another address. Start it again from the app.` The form reached `/oauth/callback` without the [sign-in cookie](https://frontmcp.dev/reference/auth/local#the-sign-in-cookie) that came with the page. The user finished in another browser, the browser blocks cookies, or your page sends its form to another host than the one that served it. Post to `callbackPath`, on the same host. ### `Invalid or missing CSRF token` A consent choice, or an `auth.ui` page, submitted without its `csrf` value. The built-in consent screen has it in a hidden field; on an `auth.ui` page it's `window.__FRONTMCP_AUTH__.csrfToken`, which ``, `submitFinish()` and `submitExtra()` add, and a form you write yourself must include. ### `Cross-origin request blocked` The browser sent the sign-in form from a page on another host (its `Origin` or `Referer`). Serve the sign-in page from FrontMCP itself. FrontMCP compares that host with the request's `Host` and `X-Forwarded-Host`, so a proxy that changes `Host` must send `X-Forwarded-Host` with the public one. ### The built-in page shows instead of your `auth.ui` component FrontMCP couldn't build the file and logged why, as `Failed to build auth.ui page for slot "login": …`: - `ENOENT: no such file or directory`: the path is wrong. A relative path is resolved from the file with `@FrontMcp` or `@App`, or from the working directory if FrontMCP logged `auth.ui paths will resolve against process.cwd()`. Use an absolute path to be sure. - `Dynamic require of "path" is not supported`: the server runs FrontMCP 1.8.7 or earlier as an ES module (`import`, with `"type": "module"`), which couldn't build `auth.ui` pages. Upgrade: since 1.9.0 they build in ES module projects too. FrontMCP doesn't try a broken file again until the server restarts. ### `Invalid tool selection. Please restart authorization and choose from the available tools.` The consent form sent a tool that wasn't on the screen, such as an excluded tool, or a name that doesn't exist. Only tick tools from the screen.