@FrontMcp

@FrontMcp(options)
export default class Server {}

Reference

@FrontMcp(options)

Apply @FrontMcp to an empty class in your server's entry file.

import "reflect-metadata";
import { FrontMcp, LogLevel } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  http: { port: 3000 },
  logging: { level: LogLevel.Info },
})
export default class Server {}

See more examples below.

Options

Required:

Shared by every app:

How the server behaves toward clients. These all work in the Playground:

How the server is deployed. These configure a real process, so the Playground ignores them:

Other features:

info

info has no description field. One is silently dropped: use instructions to describe the server to the model.

http

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  http: {
    port: 8080,
    entryPath: "/mcp",
    cors: { origin: ["https://desk.example.com"], credentials: true },
    routes: [{ method: "GET", path: "/exports", handler: (req, res) => res.json({ format: req.query.format ?? "csv" }) }],
  },
})
export default class Server {}

transport

Clients that speak MCP 2026-07-28 don't use sessions, so most of these only matter for older clients. A session id is encrypted with MCP_SESSION_SECRET. Since 1.8.6, a request whose id was minted under another secret gets 404 invalid session id (before 1.8.6, session not initialized), and the client starts over with initialize, so changing the secret ends every open session once. This was checked on a Node server, since the Playground has no sessions.

auth

auth sets who may connect, and apps inherit it. An app's own auth doesn't change who may call its tools on the shared endpoint: see Auth for one app. Auth modes covers every mode and its options.

In local and remote mode, only registered clients can sign in, since requireRegisteredClients defaults to true, and a client is granted only the scopes listed in allowedScopes. See Local auth.

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  auth: { mode: "static", tokens: [process.env.DESK_API_KEY!] },
})
export default class Server {}

The Playground's client can't send credentials, so this runs in a project, not in the Playground. Authenticating Clients walks through each mode.

Starting the server

With the default serve: true, importing the class starts an HTTP server. With the environment variable FRONTMCP_STDIO=1 (or true), it connects over stdio instead and opens no port, for clients that launch the server as a subprocess.

To decide when the server starts, set serve: false and start it yourself:

import "reflect-metadata";
import { FrontMcp, FrontMcpInstance } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

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

@FrontMcp({ ...options, serve: false })
export default class Server {}

await connectToDatabase();
await FrontMcpInstance.bootstrap(options);

FrontMcpInstance also has runStdio(options), createHandler(options) for serverless platforms, and createFetchHandler(options), which is what the Playground uses. To call a server in your own process, see create() and createDirect() and connect().

Caveats

• Declare one @FrontMcp per server. The class body is ignored.
• Options FrontMCP doesn't know are dropped without an error, including info.description and a top-level prompts. Check the spelling of anything that seems to have no effect.
• The MCP endpoint is at the root path unless you set http.entryPath.
• The Playground runs your options through FrontMcpInstance.createFetchHandler(), in your browser, with a minimal AsyncContext so that calls overlap as they do on Node (FrontMCP's browser build serves one request at a time without one). It opens no port, and serve, http, transport and the storage options have no effect there. auth does apply, but the Playground's client never sends credentials: a mode that requires them (such as static) refuses every request, and one that allows anonymous callers treats the Playground as anonymous. See Authenticating Clients.

Usage

Declaring a server

info and apps are all a server needs. Clients receive info with every response: open the Wire tab and look at _meta in any response.

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

@FrontMcp({
  info: { name: "help-desk", title: "Help Desk", version: "1.4.0", websiteUrl: "https://desk.example.com" },
  apps: [HelpDeskApp],
})
export default class Server {}

Tools every app shares

tools and resources on @FrontMcp belong to no app: every app serves them, and they're listed once, with their own names. Use them for what isn't any app's, like a health check:

import { FrontMcp } from "@frontmcp/sdk";
import { BillingApp, HelpDeskApp } from "./apps";
import { Ping, ServerStatus } from "./shared";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp, BillingApp],
  tools: [Ping],
  resources: [ServerStatus],
})
export default class Server {}

@FrontMcp has no prompts: put prompts in an app. Changed in 1.9.1: before, FrontMCP accepted tools and resources here but never registered them, so clients couldn't see or call them.

Giving the model instructions

Tool descriptions explain each tool. instructions explains the server: which tool to start with, how the tools fit together, what not to do. Clients read it from server/discover and usually add it to the model's context, so keep it short.

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

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  instructions:
    "Support ticket tools. Find tickets with search_tickets before acting on them. " +
    "Never close a ticket the customer hasn't confirmed is solved.",
})
export default class Server {}

Asking the user for input

this.elicit() pauses a tool to ask the user a question, and it only works when the server turns elicitation on. The Call tab shows the form a client would show; answer it to finish the call.

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

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  elicitation: { enabled: true },
})
export default class Server {}

Without elicitation: { enabled: true }, the same call fails. See the troubleshooting entry.

Paging long tool lists

Once a server has more than 40 tools, tools/list returns them 40 at a time, with a nextCursor for the next page. Change both numbers with pagination. Here the threshold is four tools, and there are five, so they come two per page:

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

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  pagination: { tools: { mode: "auto", autoThreshold: 4, pageSize: 2 } },
})
export default class Server {}

A client reads every tool by following nextCursor until there isn't one. mcp.tools.list() does that for you since 1.8.6; before, it returned only the first page. A DirectClient from connect() or server.connect() does it too: its list methods follow every page, listResources(), listResourceTemplates() and listPrompts() since 1.8.7. So does listTools() on the server itself, since 1.9; before, it returned only the first page. This test sends the requests itself, to show each page.

Setting defaults for every tool

Some options set a default for every tool on the server. An app's own setting overrides the server's, and a tool's overrides both.

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

@Tool({ name: "average_reply_hours", description: "Average hours to first reply this week", inputSchema: {} })
class AverageReplyHours extends ToolContext {
  async execute() {
    const replies: number[] = [];
    return { hours: replies.reduce((a, b) => a + b, 0) / replies.length }; // 0 / 0 is NaN
  }
}

@App({ id: "reports", name: "Reports", tools: [AverageReplyHours] })
class ReportsApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [ReportsApp],
  output: { allowNonFinite: true },
})
export default class Server {}

ui.servingMode sets a default the same way, for the serving mode of every tool with a widget that doesn't set its own: @FrontMcp({ ui: { servingMode: "static" } }), overridden by @App({ ui: { servingMode } }) for an app's tools, and by a tool's own ui.servingMode. New in 1.9.4. Defaults for the server and an app shows it.

Serving HTTP routes next to MCP

Not everything a help desk serves is MCP. A spreadsheet wants a CSV export, and the billing system calls a webhook when an invoice is paid. http.routes adds plain HTTP endpoints on the MCP endpoint's port, so they don't need a second server:

import "reflect-metadata";
import { FrontMcp } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";
import { markPaid, ticketsCsv } from "./store";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  auth: { mode: "static", tokens: [process.env.DESK_API_KEY!] },
  http: {
    routes: [
      {
        method: "GET",
        path: "/exports/:status",
        auth: true, // the same credentials as the MCP endpoint
        handler: (req, res) => {
          res.setHeader("Content-Type", "text/csv");
          res.send(ticketsCsv(req.params?.status ?? "open"));
        },
      },
      {
        method: "POST",
        path: "/webhooks/billing",
        handler: (req, res) => {
          markPaid(req.body.invoice);
          res.status(202).json({ received: req.body.invoice });
        },
      },
    ],
  },
})
export default class Server {}

A handler is Express-style, (req, res, next). req.params holds the path's :status, req.query the query string, req.headers the headers, and req.body a JSON or form body, already parsed. res has status(), json(), send() and setHeader(). This server answers:

auth: true runs the check the MCP endpoint runs, before the handler:

• Without valid credentials, the route answers 401 with the challenge the MCP endpoint sends. With an identity provider (transparent mode), it points at the resource metadata: Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource".
• A valid token that lacks one of auth.requiredScopes gets 403 {"error":"Forbidden"}, with error="insufficient_scope" and the scopes it needs in the challenge.
• Otherwise the handler runs, and req.authSession says who called: user holds the token's claims (sub, scope, and for a JWT the rest of them), and token the token itself. A static key's user.sub is static: and a hash of the key.
• A server that lets anonymous callers in lets them into these routes too. In public mode, the default, and with allowAnonymous, a request without a token runs the handler as a new anonymous caller each time, whose req.authSession.user.sub starts with anon:. If a route needs a real caller, refuse those in the handler.

throttle.ipFilter applies to every route, before auth: a refused address gets 403 {"error":"forbidden","message":"Client IP rejected by ipFilter"}.

The content type. FrontMCP's Express server sets Content-Type: application/json; charset=utf-8 on every response before a handler runs. That suits res.json(), but a CSV string sent with res.send() goes out labelled as JSON. Set the type first, as the export does.

Reserved paths. A route can't take a path FrontMCP serves itself:

• the MCP endpoint and the /sse and /message paths next to it: /, /sse and /message by default, or /mcp, /mcp/sse and /mcp/message with entryPath: "/mcp";
• /health and /metrics;
• anything under /oauth/ or /.well-known/.

Such a route stops the server from starting: see the troubleshooting entry. /healthz and /readyz aren't on the list, and your routes are registered before FrontMCP's health checks, so a route on either replaces the health check.

Where routes are served. FrontMCP's Node server serves them, whether you start it by importing the class or with bootstrap(), and so does createHandler(). createFetchHandler() doesn't: on Cloudflare Workers, Deno and Bun, and in the Playground, a request to a route gets 404. It still refuses reserved paths. Everything else in this section was checked on a Node server.

Large files. A tool's result, like a resource's contents, travels inside one JSON-RPC response. For an export of many megabytes, serve the file from a route and have the tool return a resource_link to it: the result carries only the link, and the file goes out on a request of its own when someone follows it. With auth: true on the route, that request needs the same credentials as the MCP endpoint.

import { App, FrontMcp, Tool, ToolContext, z, type ServerRequest, type ServerResponse } from "@frontmcp/sdk";
import { ticketsCsv } from "./store";

const PUBLIC_URL = "https://desk.example.com"; // where clients reach this server

@Tool({
  name: "export_tickets",
  description: "Export the tickets with a status as a CSV file, and return a link to it",
  inputSchema: { status: z.enum(["open", "closed"]) },
  outputSchema: "resource_link",
})
class ExportTickets extends ToolContext {
  async execute({ status }: { status: "open" | "closed" }) {
    return { type: "resource_link" as const, uri: `${PUBLIC_URL}/exports/${status}`, name: `${status}-tickets.csv`, mimeType: "text/csv" };
  }
}

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

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  http: {
    routes: [
      {
        method: "GET" as const,
        path: "/exports/:status",
        handler: (req: ServerRequest, res: ServerResponse) => {
          res.setHeader("Content-Type", "text/csv");
          res.send(ticketsCsv(req.params?.status ?? "open"));
        },
      },
    ],
  },
};

@FrontMcp(config)
export default class Server {}

On a Node server, following the link returns the two open tickets as text/csv.

Using your own HTTP server

FrontMCP's Node server is built on Express. http.hostFactory replaces Express with a server of your own: a FrontMcpServer subclass, or a function that returns one. FrontMCP still decides what to serve, the MCP endpoint, discovery documents, OAuth, health checks and your routes, and registers each with your server. Your server decides how requests reach them.

To add MCP to a Node server you already run, you don't need one: createHandler() returns FrontMCP's Express app as a (req, res) handler, to call with the requests MCP should answer.

FrontMCP calls these methods, in this order:

The handlers expect Express's request and response, so a host gives them what they use. On the request: path, query, params, headers, and body, parsed from JSON or a form. On the response: status(), which returns the response, json(), send() and redirect(), besides Node's own setHeader(), writeHead(), write() and end(), which streamed answers use. This host does it with node:http alone:

import http from "node:http";
import { FrontMcpServer, type HttpMethod, type ServerRequest, type ServerRequestHandler, type ServerResponse } from "@frontmcp/sdk";

type Layer = { method?: HttpMethod; path: string; prefix: boolean; handler: ServerRequestHandler };

export class NodeHost extends FrontMcpServer {
  private layers: Layer[] = [];
  private server?: http.Server;

  registerMiddleware(path: string, handler: ServerRequestHandler) {
    this.layers.push({ path, prefix: true, handler });
  }

  registerRoute(method: HttpMethod, path: string, handler: ServerRequestHandler) {
    this.layers.push({ method, path, prefix: false, handler });
  }

  enhancedHandler(handler: ServerRequestHandler) {
    return handler;
  }

  prepare() {}

  getHandler() {
    return (req: http.IncomingMessage, res: http.ServerResponse) =>
      this.handle(req, res).catch(() => {
        if (!res.headersSent) res.writeHead(500).end();
      });
  }

  async start(portOrSocketPath?: number | string, bindAddress?: string) {
    this.server = http.createServer(this.getHandler());
    await new Promise<void>((resolve) => {
      if (typeof portOrSocketPath === "string") this.server!.listen(portOrSocketPath, resolve);
      else this.server!.listen(portOrSocketPath, bindAddress, resolve);
    });
  }

  override async stop() {
    await new Promise((resolve) => this.server?.close(resolve));
  }

  private async handle(req: http.IncomingMessage, res: http.ServerResponse) {
    const url = new URL(req.url ?? "/", "http://localhost");
    let body: unknown;
    try {
      body = await readBody(req);
    } catch {
      return void res.writeHead(400).end(); // not JSON
    }
    // What FrontMCP's handlers read and call, as on Express
    const request = Object.assign(req, { path: url.pathname, query: Object.fromEntries(url.searchParams), body });
    const response = Object.assign(res, {
      status: (code: number) => {
        res.statusCode = code;
        return res;
      },
      json: (payload: unknown) => {
        if (!res.hasHeader("content-type")) res.setHeader("content-type", "application/json; charset=utf-8");
        res.end(JSON.stringify(payload));
      },
      send: (payload: unknown) => res.end(typeof payload === "string" || payload instanceof Uint8Array ? payload : JSON.stringify(payload)),
      redirect: (status: number | string, location?: string) => {
        res.writeHead(typeof status === "number" ? status : 302, { location: typeof status === "number" ? location : status }).end();
      },
    });

    // Offer the request to each handler in the order FrontMCP registered them, until one answers
    const layers = this.layers.filter((layer) => !layer.method || layer.method === req.method);
    const next = async (i: number): Promise<void> => {
      if (i === layers.length) return void res.writeHead(404).end();
      const params = matchPath(layers[i], url.pathname);
      if (!params) return next(i + 1);
      Object.assign(request, { params });
      await layers[i].handler(request as unknown as ServerRequest, response as unknown as ServerResponse, () => next(i + 1));
    };
    await next(0);
  }
}

// "/exports/:status" matches "/exports/open" with { status: "open" }; a middleware's path also matches what's below it
function matchPath(layer: Layer, pathname: string): Record<string, string> | undefined {
  const want = layer.path.split("/").filter(Boolean);
  const got = pathname.split("/").filter(Boolean);
  if (layer.prefix ? got.length < want.length : got.length !== want.length) return undefined;
  const params: Record<string, string> = {};
  for (const [i, part] of want.entries()) {
    if (part.startsWith(":")) params[part.slice(1)] = decodeURIComponent(got[i]);
    else if (part !== got[i]) return undefined;
  }
  return params;
}

async function readBody(req: http.IncomingMessage) {
  const type = req.headers["content-type"] ?? "";
  const form = type.includes("application/x-www-form-urlencoded");
  if (!form && !type.includes("application/json")) return undefined;
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  const text = Buffer.concat(chunks).toString("utf8");
  if (!text) return undefined;
  return form ? Object.fromEntries(new URLSearchParams(text)) : JSON.parse(text);
}

import "reflect-metadata";
import { FrontMcp } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";
import { NodeHost } from "./node-host";

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  http: { port: 3000, hostFactory: () => new NodeHost() },
})
export default class Server {}

On a Node server, this host served server/discover and tools/call to a 2026-07-28 client, an initialize session and a streamed tools/call to a 2025-06-18 client, /healthz, /readyz, the resource metadata document, and an http.routes route with auth: true. The Playground runs no HTTP server, so it never calls a host.

Some of what the Express server does, a host of your own has to do itself: cors, bodyLimit, securityHeaders with its nosniff and X-Frame-Options defaults, the Host check of security.dnsRebindingProtection, and the JSON Content-Type default. With this host, a request from an origin listed in cors gets no CORS headers. The function form of hostFactory is called once, with the http options except hostFactory, defaults filled in (port, entryPath, bodyLimit), so your server can read them. An instance, hostFactory: new NodeHost(), works the same way, without them.

FrontMcpServer, HttpMethod, ServerRequestHandler, ServerRequest and ServerResponse come from @frontmcp/sdk. FrontMCP's Express host class isn't exported, so a host extends FrontMcpServer directly.

Troubleshooting

@FrontMcp invalid metadata for "apps"

The full message goes on: apps items must be annotated with @App() | @FrontMcpApp() or be a valid remote app configuration. An entry in apps is a class without @App. Often it's a tool or a provider listed directly on the server:

// 🚩 A tool is not an app
@FrontMcp({ info, apps: [SearchTickets] })

// ✅ Put the tool in an app, and the app on the server
@App({ id: "help-desk", name: "Help Desk", tools: [SearchTickets] })
class HelpDeskApp {}

@FrontMcp({ info, apps: [HelpDeskApp] })

Invalid option: expected one of 0|1|2|3|4|100

The error's path is logging.level. The level is a LogLevel enum value, not a string:

// 🚩 A string
logging: { level: "info" }

// ✅ The enum
import { LogLevel } from "@frontmcp/sdk";
logging: { level: LogLevel.Info }

Elicitation is disabled in server configuration

A tool called this.elicit(), but the server doesn't have elicitation turned on, so the call failed with this message:

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

@Tool({ name: "close_ticket", description: "Close a ticket once the user confirms", inputSchema: { id: z.string() } })
class CloseTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    const answer = await this.elicit(`Close ticket ${id}?`, z.object({ confirm: z.boolean() }));
    return { id, status: answer.content?.confirm ? "closed" : "open" };
  }
}

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

// 🚩 No `elicitation: { enabled: true }`
@FrontMcp({ info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp] })
export default class Server {}

Add elicitation: { enabled: true } to @FrontMcp. If the server runs as several processes, also give it a redis, so an answer can reach whichever process asked.

Authorities configuration required, or Invalid authorities rule

The server didn't start, for one of three reasons:

• An entry declares authorities, a tool, resource, template, prompt, agent, a tool inside an agent, or a skill, and @FrontMcp has no authorities option to check it with.
• A rule checks nothing: {}, an empty list, an unknown field like role:, or a profile name inside anyOf. The message names the entry. Such a rule used to let every caller in; since FrontMCP 1.8.3 the server refuses it instead.
• A rule names a profile the authorities option doesn't define, like a typo: Invalid authorities rule: Tool "close_ticket": authorities names an unknown profile "lead". Changed in 1.8.4: before, such a server started and then refused every caller.

import { test, expect } from "@frontmcp/testing";
import { FrontMcpInstance } from "@frontmcp/sdk";
import { ArchiveApp, HelpDeskApp } from "./apps";
import { authorities } from "./main";

const info = { name: "help-desk", version: "1.0.0" };

test("an entry with authorities, and no authorities option", async () => {
  await expect(FrontMcpInstance.createDirect({ info, apps: [HelpDeskApp] })).rejects.toThrow('Authorities configuration required: Tool "close_ticket"');
});

test("a rule that checks nothing", async () => {
  await expect(FrontMcpInstance.createDirect({ info, apps: [HelpDeskApp, ArchiveApp], authorities })).rejects.toThrow(
    'Invalid authorities rule: Tool "reopen_ticket": authorities checks nothing',
  );
});

test("a profile name the option doesn't define", async () => {
  const typo = { profiles: { leads: { roles: { any: ["lead"] } } } };
  await expect(FrontMcpInstance.createDirect({ info, apps: [HelpDeskApp], authorities: typo })).rejects.toThrow(
    'Invalid authorities rule: Tool "close_ticket": authorities names an unknown profile "lead"',
  );
});

test("with the option, and a rule that checks a role, the server starts", async ({ mcp }) => {
  expect(await mcp.tools.call("close_ticket", { id: "T-1" })).toBeError("AUTHORITY_DENIED");
});

Add the authorities option, and fix the rule. To leave an entry open to everyone, remove its authorities.

Custom http.route … collides with the reserved FrontMCP path

The server didn't start, because a route in http.routes takes a path FrontMCP serves itself. The full message names both paths and the rule: Custom http.route "GET /health" collides with the reserved FrontMCP path "/health". Reserved prefixes are the MCP entry path (and its /sse + /message siblings), /oauth/*, /.well-known/*, /health, and /metrics. Choose a different path.

import { test, expect } from "@frontmcp/testing";
import { FrontMcpInstance, type ServerRequestHandler } from "@frontmcp/sdk";
import { HelpDeskApp } from "./help-desk.app";

const info = { name: "help-desk", version: "1.0.0" };
const ok: ServerRequestHandler = (_req, res) => res.json({ ok: true });
const serve = (path: string, entryPath = "") =>
  FrontMcpInstance.createFetchHandler({ info, apps: [HelpDeskApp], http: { entryPath, routes: [{ method: "GET", path, handler: ok }] } });

test("a route on /health", async () => {
  await expect(serve("/health")).rejects.toThrow('Custom http.route "GET /health" collides with the reserved FrontMCP path "/health".');
});

test("a route under /.well-known", async () => {
  await expect(serve("/.well-known/desk.json")).rejects.toThrow('collides with the reserved FrontMCP path "/.well-known"');
});

test("with entryPath /mcp, /mcp/sse is taken and / is free", async () => {
  await expect(serve("/mcp/sse", "/mcp")).rejects.toThrow('collides with the reserved FrontMCP path "/mcp/sse"');
  await expect(serve("/", "/mcp")).resolves.toBeDefined();
});

test("/healthz isn't reserved", async () => {
  await expect(serve("/healthz")).resolves.toBeDefined();
});

Move the route to a path of its own. To add a check to FrontMCP's health endpoints, use health.probes instead: see Health checks.

My client gets 404 or Cannot POST /mcp

The client is using a different path from the server. The MCP endpoint is at the root, http://localhost:3000, unless http.entryPath says otherwise. Either point the client at the root, or set http: { entryPath: "/mcp" }. If apps are standalone or the server uses splitByApp, each app has its own path under the entry path, like /mcp/billing.

A route answers 404 {"error":"Not Found","entryPaths":["/"]}

The server runs through createFetchHandler(), as on Cloudflare Workers, Deno and Bun, and it doesn't serve http.routes. The 404 lists the paths it serves MCP on. Answer the route's path in your own fetch code before calling the handler, or run the server on Node: see Serving HTTP routes next to MCP.

A web page can't read the server's responses

Browsers block cross-origin reads unless the server sends CORS headers, and since FrontMCP 1.7 it sends none by default. The request still reaches the server; the browser hides the response. List the origins that need access:

http: { cors: { origin: ["https://desk.example.com"] } }

FrontMCP then also exposes the Mcp-Session-Id header, which clients using sessions need. CORS only affects browsers. It isn't access control; use auth for that.

Clients on other machines can't connect

The server listens on 127.0.0.1 by default, so only the same machine can reach it. Set http: { security: { bindAddress: "all" } }, or the FRONTMCP_BIND_ADDRESS=all environment variable (handy in a Dockerfile), and put auth in front of anything you expose.