Local auth

@FrontMcp({ auth: { mode: "local", ...options } })

Reference

auth: { mode: "local" }

Set it in @FrontMcp({ auth }). The options below are all optional.

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";
import { findAgentByDeskKey } from "./agents";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  auth: {
    mode: "local",
    allowedScopes: ["tickets:read", "tickets:write"],
    login: { title: "Sign in to Help Desk", fields: { deskKey: { type: "password", label: "Desk key", required: true } } },
    authenticate: async ({ fields }) => {
      const agent = await findAgentByDeskKey(fields.deskKey);
      return agent ? { ok: true, sub: agent.id, claims: { team: agent.team } } : { ok: false, message: "That desk key isn't valid." };
    },
  },
})
export default class Server {}

See more examples below.

Options

Endpoints

Local mode adds these routes to the server, next to the MCP endpoint:

There's no revocation, introspection or OpenID discovery: /oauth/revoke, /oauth/introspect and /.well-known/openid-configuration are 404.

Every response of /oauth/token and /oauth/register, errors included, carries Cache-Control: no-store and Pragma: no-cache, so no proxy or browser keeps a token or a client secret (RFC 6749 §5.1). (Changed in 1.9.3: before, they had neither.)

The URLs in the discovery documents come from each request: the address it was sent to under createFetchHandler(), and its Host header and protocol on FrontMCP's Node server (X-Forwarded-Host and X-Forwarded-Proto only when FRONTMCP_TRUST_PROXY is set), or FRONTMCP_PUBLIC_URL when it's set. issuer, and the protected-resource metadata's authorization_servers, are the token issuer, so they name local.issuer when you set it. scopes_supported lists the entries of allowedScopes that have no *. For a server at http://localhost:3000 with the default allowedScopes, the authorization-server metadata is:

{
  "issuer": "http://localhost:3000",
  "authorization_endpoint": "http://localhost:3000/oauth/authorize",
  "token_endpoint": "http://localhost:3000/oauth/token",
  "userinfo_endpoint": "http://localhost:3000/oauth/userinfo",
  "jwks_uri": "http://localhost:3000/.well-known/jwks.json",
  "registration_endpoint": "http://localhost:3000/oauth/register",
  "token_endpoint_auth_methods_supported": [],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "authorization_response_iss_parameter_supported": true,
  "client_id_metadata_document_supported": true
}

The flow a client follows

This is the OAuth 2.1 authorization-code flow with PKCE, which is what MCP clients implement. The client does every step; the user only sees the sign-in page.

1. The client sends an MCP request without a token. FrontMCP answers 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource".
2. It reads that document, then the authorization-server metadata of the server it names, which is the same server.
3. It registers at /oauth/register with its redirect URIs, unless it's pre-registered or uses a CIMD URL as its client_id.
4. It makes a random code_verifier, and opens /oauth/authorize in the user's browser with code_challenge (the verifier's SHA-256, base64url) and its client_id, redirect_uri and state. The browser gets the sign-in page and keeps the sign-in cookie that comes with it.
5. The user fills in the sign-in page. Its form posts to /oauth/callback, with the cookie, which redirects the browser to redirect_uri?code=…&state=…&iss=….
6. The client posts the code and the code_verifier to /oauth/token and gets an access token and a refresh token.
7. It sends Authorization: Bearer <access token> on every MCP request, and uses the refresh token for a new pair before the hour is up.

Signing in, step by step sends each of these requests.

/oauth/authorize parameters

Scopes

A token gets the scopes the client asked for that allowedScopes lists, in the order asked, and the others are dropped without an error. The sign-in page lists the granted ones, and the token response's scope says what was granted. With the default allowedScopes, only openid, profile, email and offline_access can be granted, so a scope of your own, like tickets:read, is dropped until you list it.

Tokens

The access token is a JWT signed with HS256 and the JWT_SECRET environment variable. It holds:

• An access token lasts 3600 seconds and a refresh token 30 days. Neither can be configured.
• Every refresh returns a new refresh token, and the old one stops working.
• Using a code twice fails, and also cancels the refresh token the first exchange issued.
• FrontMCP checks a token's signature and expiry, that its iss is the one this server would issue for the request, and that its aud is the URL the request came to, or one of expectedAudience when you set it. With expectedAudience, a token issued at any of the listed addresses is accepted at the others too. So a token works only on the server that issued it, even when other servers share its JWT_SECRET, and only at the address it was issued at: they answer 401 with unexpected "iss" claim value or Token audience does not match this resource.
• this.auth reads the token: user.sub, user.email and user.name from the claims of the same name, scopes from scope, and every claim in claims.

Users

• Without authenticate, sub is a hash of the email address, shaped like a UUID. The same address, in any case, is always the same user, so a user keeps their data across sign-ins.
• With authenticate, sub is the sub it returns, or a hash of one login field when login.subject is { fromField, strategy: "per-account" }, or a hash of anonymousSubject.
• Local mode keeps no list of users: a user is whoever signs in.

authenticate(input, ctx)

roles is one of the dropped claims. To give local users roles, return them under another name, like deskRoles, and point authorities.claimsMapping.roles at it.

Keys and signing

Without JWT_SECRET, FrontMCP logs a warning and signs with a random secret made when the process starts, so every token dies with the process, and a second instance can't read the first one's tokens. In production (NODE_ENV=production) the server doesn't start instead: createFetchHandler() and FrontMCP's Node server reject when they're called, with JwtSecretRequiredError (JWT_SECRET is required in production for auth.mode "local"…), or JwtSecretWeakError for a secret under 32 bytes. On an edge isolate, which builds the server on its first request, every request gets 500 JWT_SECRET_REQUIRED or JWT_SECRET_INVALID instead: see Production secrets. (Changed in 1.8.4: createFetchHandler() used to return a handler that answered every request with that 500.) That, and registration being off in production, were checked in Node: the Playground doesn't run in production mode.

Storage

tokenStorage holds everything local mode must remember between requests: pending sign-ins, codes, refresh tokens, remembered consent, and the credential vault.

If the store can't be reached, the server fails closed: it doesn't start, and createFetchHandler() rejects with StorageConnectionError: Failed to connect to Redis: … instead of falling back to memory. The Playground has no Redis or SQLite, and neither backend was run for this page: only that failure. From FrontMCP's code: busyTimeoutMs (default 5000) is how long SQLite waits for a lock another connection holds, and reaches the store since 1.9.0 (1.8.7 accepted it and dropped it here); a database written with another encryption.secret fails with a SqliteDecryptionError that names the secret (new in 1.8.7).

dcr

A registration asks for token_endpoint_auth_method none (the default), client_secret_post or client_secret_basic, and gets a client_secret for the last two. private_key_jwt is 400 invalid_client_metadata. A registration FrontMCP can't read, like one without redirect_uris, with an empty list or with a method it doesn't know, gets 500 {"error":"server_misconfigured","code":"CONFIG_INVALID",…}, whose message blames the server's configuration: check the client's request, not your config.

this.secureStore

Local mode gives tools this.secureStore, an encrypted key-value store for secrets a user gives your server, like an API key. By default it's in memory and kept per user (sub), so it survives a new sign-in and one user can't read another's.

secureStore: { scope } keys it by "user" (the default), "session" or "global", and { redis }, { sqlite } or { backend } (an object with get, set, delete and list) change where it's kept. "session" is meant for the sessions of clients before MCP 2026-07-28; a request on MCP 2026-07-28 has no session, so there it's kept per user, like "user". Changed in 1.8.4: before, "session" used whatever session id the request named, so a caller who sent another's id read and replaced their secrets.

Anonymous tokens

With allowDefaultPublic: true, a client can post grant_type=anonymous&client_id=<anything> to /oauth/token and get a token without signing in. It's valid for a day, and the refresh token that comes with it doesn't work. Its sub is anon: and a random id, its scope is anonymousScopes, and it has anonymous: true and an aud like any other token. A caller with it is anonymous: this.auth.isAnonymous is true, and this.auth.scopes is anonymousScopes. (Before 1.8.3 the token had a plain random sub and no scopes, and its holder looked signed in.)

The sign-in cookie

A sign-in finishes only in the browser that started it. With the sign-in page, /oauth/authorize sets a cookie for this sign-in: __Host-frontmcp_signin_<id> over HTTPS (Path=/, Secure), or frontmcp_signin_<id> on Path=/oauth over HTTP, both HttpOnly, SameSite=Lax and good for 30 minutes. /oauth/callback refuses a form that doesn't bring it back, with a 400 page: This sign-in was started in another browser, or at another address. Start it again from the app. The redirect that delivers the code clears it. Each sign-in has its own cookie, so a user can have two open at once.

So someone who starts a sign-in can't send another person to the page and receive a token for them. A browser keeps it without you doing anything, but a script that walks the sign-in, like a test, must keep the cookie and send it back, as the client below does. There's no option to turn it off. (New in 1.8.3: sign-ins in progress during the upgrade have to start again.)

Caveats

• The sign-in and consent pages load their fonts and styles from Google Fonts and cdn.jsdelivr.net, so the user's browser has to reach both; their Content-Security-Policy allows those hosts. See Custom login UI.
• Links FrontMCP builds for later, like the credential-connect link and the redirect URI it gives upstream providers, start with http://localhost:<http.port> unless you set local.issuer, on every runtime. http.port defaults to the PORT environment variable, or 3000, the port FrontMCP's Node server listens on. (Changed in 1.9.2: before, they said 3001 whenever http.port wasn't set.)
• An app's own auth only applies to apps with their own endpoint (standalone or splitByApp). On the shared endpoint, a call is checked against the apps the user authorized only with incrementalAuth. See Auth for one app.

Usage

The Playground's own client can't open a browser or sign in, so in each example below the Playground runs the app without auth, and the tests start the same app with local auth through FrontMcpInstance.createFetchHandler() and send it the requests an MCP client would, and the user's browser, with its cookie. The tests send their requests to https://desk.example.com, and under createFetchHandler() the server builds its URLs, and its tokens' iss and aud, from the address a request was sent to, so that's the address they name.

Discovering the server

A client without a token gets a 401 that points to the protected-resource metadata, and that names the authorization server. Both documents are public.

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() {
    const { user, scopes } = this.auth;
    return { sub: user.sub, email: user.email ?? null, scopes };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [WhoAmI] })
export class HelpDesk {}

/.well-known/jwks.json isn't in the tests: FrontMCP makes its key with Node's crypto, which the Playground doesn't have. In Node it answers { "keys": [{ "kty": "RSA", "alg": "RS256", "use": "sig", "kid": "…", "n": "…", "e": "AQAB" }] }.

Signing in, step by step

oauth-client.ts is a small MCP client: one method per request of the flow. The tests walk through it and then call a tool with the token.

import { FrontMcpInstance } from "@frontmcp/sdk";

type Config = Parameters<typeof FrontMcpInstance.createFetchHandler>[0];
type Handler = (request: Request) => Promise<Response>;

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<string, string>();

  private constructor(
    private readonly server: Handler,
    private readonly origin: string,
  ) {}

  /** A client of a new server with this config, reached at this address. */
  static async for(config: Config, origin = SERVER) {
    return new OAuthClient((await FrontMcpInstance.createFetchHandler(config)) as Handler, origin);
  }

  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(this.origin + 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<string, unknown> = {}) {
    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<string, string> = {}) {
    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<string, string>) {
    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<string, string>) {
    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<string, string>, params: Record<string, string> = {}) {
    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<string, unknown> = {}) {
    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(/=+$/, "");
}

A real client opens /oauth/authorize in the user's browser and catches the redirect to redirect_uri (a local port, for a desktop client). The browser keeps the cookie and follows the sign-in page's form to /oauth/callback on its own; the test does the same by keeping the cookie in client.cookies and reading pending_auth_id from the page.

By default iss and aud are both the address the request came to, so a token issued at one address is refused at any other, with unexpected "iss" claim value first. With local.issuer, iss is the same everywhere and aud still ties the token to its address. FrontMCP's Node server does the same (checked in Node).

Refreshing a token

Before the access token's hour is up, the client posts its refresh token. It gets a new access token and a new refresh token, and the old refresh token stops working.

import { test, expect } from "@frontmcp/testing";
import { OAuthClient, claimsOf } from "./oauth-client";
import { config } from "./server";

test("a refresh returns a new pair and retires the old refresh token", async () => {
  const client = await OAuthClient.for(config);
  const first = await client.signIn({ email: "nour@example.com" }, { scope: "tickets:read" });

  const refreshed = await client.refresh(first.refresh_token);
  expect(refreshed.status).toBe(200);
  expect(refreshed.body).toMatchObject({ token_type: "Bearer", expires_in: 3600, scope: "tickets:read" });
  expect(refreshed.body.refresh_token).not.toBe(first.refresh_token);
  expect(claimsOf(refreshed.body.access_token)).toMatchObject({ sub: claimsOf(first.access_token).sub, aud: claimsOf(first.access_token).aud });

  const again = await client.refresh(first.refresh_token);
  expect(again).toEqual({ status: 400, body: { error: "invalid_grant", error_description: "Refresh token is invalid or expired" } });
});

test("a code works once, and using it again cancels its refresh token", async () => {
  const client = await OAuthClient.for(config);
  await client.register();
  const { pendingAuthId } = await client.authorize();
  const { code } = await client.submit({ pending_auth_id: pendingAuthId!, email: "nour@example.com" });

  const tokens = await client.exchange(code!);
  expect(tokens.status).toBe(200);
  expect(await client.exchange(code!)).toEqual({ status: 400, body: { error: "invalid_grant", error_description: "Authorization code has already been used" } });
  expect((await client.refresh(tokens.body.refresh_token)).status).toBe(400);
});

test("the code only goes to the client that asked, with its verifier", async () => {
  const client = await OAuthClient.for(config);
  await client.register({ redirect_uris: ["http://localhost:3000/callback", "http://localhost:4000/callback"] });
  const { pendingAuthId } = await client.authorize();
  const { code } = await client.submit({ pending_auth_id: pendingAuthId!, email: "nour@example.com" });
  const exchange = (changes: Record<string, string>) =>
    client.token({ grant_type: "authorization_code", code: code!, redirect_uri: "http://localhost:3000/callback", client_id: client.clientId, code_verifier: client.verifier, ...changes });

  expect(await exchange({ code_verifier: "not-the-verifier-this-client-started-with-0123" })).toEqual({ status: 400, body: { error: "invalid_grant", error_description: "PKCE verification failed" } });
  expect(await exchange({ redirect_uri: "http://localhost:4000/callback" })).toEqual({ status: 400, body: { error: "invalid_grant", error_description: "Redirect URI does not match" } });
  expect(await exchange({ client_id: "someone-else" })).toEqual({ status: 400, body: { error: "invalid_grant", error_description: "Client ID does not match" } });
  expect((await exchange({})).status).toBe(200); // none of those used the code up
});

test("a client registered without refresh_token can still refresh", async () => {
  const client = await OAuthClient.for(config);
  await client.register({ grant_types: ["authorization_code"] });
  const { refresh_token } = await client.signIn({ email: "nour@example.com" });
  expect((await client.refresh(refresh_token)).status).toBe(200);
});

A failed exchange doesn't use the code up: the client that started the sign-in can still exchange it. grant_types from registration isn't enforced: a client registered with only authorization_code can refresh too. A code lasts 60 seconds and an open sign-in page 10 minutes; those are fixed in the build, and the Playground doesn't wait that long.

Checking users yourself

authenticate runs when the sign-in form is submitted. Here the sign-in page asks for a desk key instead of an email, and authenticate looks the key up. A wrong key shows the page again with a message; a right one signs the agent in with their own id and team.

import { HelpDesk } from "./help-desk.app";

const agents: Record<string, { id: string; team: string }> = {
  "dk-7f3a": { id: "agent-nour", team: "billing" },
  "dk-91c0": { id: "agent-sam", team: "hardware" },
};

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  auth: {
    mode: "local" as const,
    login: {
      title: "Sign in to Help Desk",
      fields: { deskKey: { type: "password" as const, label: "Desk key", required: true } },
    },
    authenticate: async ({ fields }: { fields: Record<string, string> }) => {
      const agent = agents[fields.deskKey];
      if (!agent) return { ok: false as const, message: "That desk key isn't valid.", retryField: "deskKey" };
      return { ok: true as const, sub: agent.id, claims: { team: agent.team, roles: ["admin"] } };
    },
  },
};

authenticate can reach your own services through ctx.get() and ctx.fetch(). When login.fields replaces the email field, add authenticate: without it, the form still has to carry an email, and every sign-in fails with Email is required.

Letting only known clients in

/oauth/authorize only starts a sign-in for a client it knows: one that registered, one listed in dcr.clients, or a CIMD URL. So it knows the client's redirect URIs, and the code only goes to one of them. requireRegisteredClients: false turns that off. Then any client_id gets the sign-in page, with any redirect URI, and the code goes there: someone can send a user a link to your real sign-in page that ends with their own redirect URI, and get a token for that user.

import { HelpDesk } from "./help-desk.app";

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  auth: { mode: "local" as const },
};

/** No registration: the only clients are the ones listed here. */
export const listed = {
  ...config,
  auth: {
    mode: "local" as const,
    dcr: {
      enabled: false,
      clients: [{ clientId: "desk-cli", redirectUris: ["http://localhost:3000/callback"], clientName: "Desk CLI" }],
    },
  },
};

// 🚩 For development only: any client_id, any redirect URI
export const anyClient = { ...config, auth: { mode: "local" as const, requireRegisteredClients: false } };

Controlling registration

dcr decides who may register and with which redirect URIs, and dcr.clients registers clients in code. A client registered with a secret must send it with every token request.

import { HelpDesk } from "./help-desk.app";

const base = { info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDesk] };

/** Registration needs a token you hand out, and only for callback URLs on this machine. */
export const invited = {
  ...base,
  auth: {
    mode: "local" as const,
    dcr: { initialAccessToken: "reg-4c1f", allowedRedirectUris: ["http://localhost:*/callback"], maxDynamicClients: 1 },
  },
};

/** No registration: the clients are listed here, one of them with a secret. */
export const listed = {
  ...base,
  auth: {
    mode: "local" as const,
    dcr: {
      allowedClientIds: ["desk-cli", "desk-web"],
      clients: [
        { clientId: "desk-cli", redirectUris: ["http://localhost:3000/callback"] },
        { clientId: "desk-web", clientSecret: "s3cr3t-for-the-web-app", tokenEndpointAuthMethod: "client_secret_post" as const, redirectUris: ["http://localhost:3000/callback"] },
      ],
    },
  },
};

Keeping a secret per user

A user gives your server an API key once, and it's there the next time they sign in. this.secureStore keeps it encrypted, under the user's sub.

import { App, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "save_crm_key", description: "Remember the user's CRM API key", inputSchema: { key: z.string() } })
export class SaveCrmKey extends ToolContext {
  async execute({ key }: { key: string }) {
    await this.secureStore.set("crm-key", key);
    return { saved: true };
  }
}

@Tool({ name: "crm_key_status", description: "Say whether the user has saved a CRM API key", inputSchema: {} })
export class CrmKeyStatus extends ToolContext {
  async execute() {
    const key = await this.secureStore.get<string>("crm-key");
    return { saved: key !== undefined, endsWith: key?.slice(-4) ?? null };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [SaveCrmKey, CrmKeyStatus] })
export class HelpDesk {}

The memory backing loses everything on restart, like the rest of local mode's state. Use secureStore: { redis } or { sqlite } to keep it.

Giving clients a token without a user

allowDefaultPublic: true lets a client get a token without a user, from /oauth/token. Requests with no token at all are still refused.

import { HelpDesk } from "./help-desk.app";

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  auth: { mode: "local" as const, allowDefaultPublic: true, anonymousScopes: ["tickets:read"] },
};

Running it in production

In production, local mode needs a fixed JWT_SECRET, shared storage if there's more than one instance, and an issuer that matches the public URL. None of this runs in the Playground:

import { FrontMcp } from "@frontmcp/sdk";
import { HelpDesk } from "./help-desk.app";
import { checkDeskKey } from "./agents";

// Environment: JWT_SECRET (openssl rand -hex 32), FRONTMCP_PUBLIC_URL=https://desk.example.com, NODE_ENV=production
@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDesk],
  auth: {
    mode: "local",
    local: { issuer: "https://desk.example.com" },
    allowedScopes: ["tickets:read", "tickets:write"],
    authenticate: checkDeskKey,
    tokenStorage: {
      redis: { host: process.env.REDIS_HOST!, port: 6379, password: process.env.REDIS_PASSWORD, tls: true, keyPrefix: "desk:auth:" },
    },
  },
})
export default class Server {}

Auth in production has the full checklist; Configuration files covers keeping secrets out of code.

Troubleshooting

Email is required

The sign-in form reached /oauth/callback without an email, and there's no authenticate. This also happens when login.fields replaced the email field: add an authenticate that checks your fields, or set requireEmail: false.

Authorization request has expired. Please try again.

The pending_auth_id the form sent isn't one the server knows. It was already used (a sign-in that succeeded removes it), the server restarted, or another instance served /oauth/authorize and memory storage doesn't share it. Use tokenStorage: { redis } with more than one instance, and start the sign-in again.

redirect_uri is not registered for this client

The client registered other redirect URIs. A registered client can only use the ones it registered, port included, so a desktop client that picks a new port each time must register again with it.

Registration allows only loopback redirect_uris (localhost, 127.0.0.0/8, ::1) without an allowlist

Registration only accepts local redirect URIs until you list others in dcr.allowedRedirectUris, or register the client in code with dcr.clients. Web clients like hosted chat apps usually identify themselves with CIMD instead.

Unknown client_id: register the client (DCR / pre-registered) or use a CIMD client-id URL

The client isn't registered, isn't in dcr.clients, and its client_id isn't a CIMD URL. Since 1.8.3 that's refused by default (requireRegisteredClients), and a redirect URI on dcr.allowedRedirectUris doesn't make a client known. With memory storage, dynamic registrations are lost on restart, so the client has to register again. In production registration is off: list the client in dcr.clients, or have it use CIMD.

error=unauthorized_client, client_id "…" is not in the configured allowlist

The client is registered, but dcr.allowedClientIds doesn't list it, so /oauth/authorize sends it back to its redirect_uri with this error, and state and iss, instead of a sign-in page. Add its id to the list, or register it in dcr.clients under an id that's listed. Changed in 1.8.4: this used to be a 400 page.

This sign-in was started in another browser, or at another address. Start it again from the app.

The sign-in form reached /oauth/callback without the cookie /oauth/authorize set. The user opened the link in one browser and finished in another, the browser blocks cookies, or the sign-in started at one host name and finished at another, like 127.0.0.1 and localhost: cookies belong to a host. A script that walks the sign-in must keep the cookie and send it back. Sign-ins started before an upgrade to 1.8.3 have to start again.

401 with unexpected "iss" claim value or Token audience does not match this resource

The token was issued by another server that shares JWT_SECRET (another iss), or at another address (another aud, and without local.issuer another iss too). Behind a proxy, the address this server checks against comes from the request's Host unless you set FRONTMCP_PUBLIC_URL, or list the URLs clients use in expectedAudience. A token issued before 1.8.3 has no aud and is refused too, with the second message. After an upgrade that changes the server's iss (to 1.8.4 on createFetchHandler() or with FRONTMCP_PUBLIC_URL, to 1.8.5 on the Node server reached at another address than localhost:<port>, or with FRONTMCP_PUBLIC_HOST or expectedAudience), older tokens are refused once with the first message. In each case the client refreshes the token or signs in again.

invalid_grant: PKCE verification failed, Redirect URI does not match, Client ID does not match, Authorization code has already been used

The token request must use the same client_id and redirect_uri as the authorize request, and the code_verifier whose SHA-256 was the code_challenge. A code works once, for 60 seconds. Authorization code is invalid or expired means it's older than that, or the server restarted with memory storage.

invalid_client: Client authentication failed

The client is registered with a secret (client_secret_post or client_secret_basic, or a clientSecret in dcr.clients) and didn't send it, or sent another one.

code_challenge: Invalid input: expected string, received undefined

The client didn't use PKCE. Local mode requires it, with code_challenge_method=S256; plain gives code_challenge_method must be "S256" (OAuth 2.1).

Every token stops working when the server restarts

JWT_SECRET isn't set, so each process signs with its own random secret. Set it to a fixed value of at least 32 bytes. Refresh tokens also need persistent tokenStorage to survive a restart.

JwtSecretRequiredError, or 500 with JWT_SECRET_REQUIRED or JWT_SECRET_INVALID

NODE_ENV is production and JWT_SECRET is missing or shorter than 32 bytes, so the server doesn't start (JwtSecretWeakError for a short one), or, on an edge isolate, every request, discovery included, fails. Set it: openssl rand -hex 32.

401 with error="invalid_token", error_description="Token is not a valid JWT"

The request's bearer token isn't a JWT at all. A JWT signed with another secret gets signature verification failed instead. Local mode only accepts tokens it issued.