FrontMCP API reference
Reference is the complete documentation for FrontMCP: every decorator, option and API, what it does, and what to do when it doesn't work. Each page is checked against the FrontMCP version this site documents, and most examples run right on the page. To learn FrontMCP from the beginning, start with the Quick Start; to see how it differs from the official MCP SDK and other TypeScript frameworks, read Compare.
Each page follows the same structure:
- Reference: the signature, every option, what it returns, and caveats.
- Usage: common tasks, each with a runnable example.
- Troubleshooting: problems you might hit, titled by what you'll see.
@frontmcp/sdk
Every page of the SDK reference, grouped, with which page answers which task, is in the SDK overview.
Decorators
Decorators declare what your server exposes.
| Decorator | Declares |
|---|---|
@FrontMcp | The server: its apps and server-wide settings |
@App | A group of tools, resources, prompts and providers |
@Tool | A function the model can call |
@Resource | Data at a fixed URI |
@ResourceTemplate | Data at a family of URIs, like ticket://{id} |
@Prompt | A reusable message template |
@Provider | A service tools can share, via dependency injection |
@Job | A unit of work that can run in the background, with retries and a run record |
@Workflow | Jobs run as steps, in dependency order |
@Agent | A tool that runs its own model loop, with its own tools and instructions |
@Skill | Instructions a client's model can find and follow, served as resources |
@Plugin | A reusable package of providers, hooks and context extensions |
@Channel | Events a server pushes to clients |
| Hook decorators | Code that runs before, after or around a stage of a call |
Context
Inside execute(), this is the call's context. Context classes lists what each kind of context has; the most used members have their own pages:
| Member | Does |
|---|---|
this.auth | Who is calling: user, scopes and roles |
this.context | The request: its id, trace, auth info and headers |
this.elicit() | Asks the user for input in the middle of a call |
this.progress() | Reports how far a long call has got |
this.notify() | Sends a log message to the client |
this.get() | Gets a provider (see @Provider) |
this.fetch() | Makes an outbound HTTP request |
this.fail() | Ends the call with an error the model can read |
this.callTool() | Calls another tool on the server |
this.respond() | Ends the call early with a finished result |
Running a server
| API | Does |
|---|---|
FrontMcpInstance | Starts the HTTP server a decorated class describes |
createFetchHandler() | A web-standard Request → Response handler, for Workers, Deno, Bun and frameworks |
create() and createDirect() | A server in your own process, called without HTTP |
connect() and client adapters | The server's tools, ready for Claude, OpenAI, LangChain or the Vercel AI SDK |
Limits, errors and the scope
- Guard options: rate limits, concurrency caps, timeouts and IP filters.
- Error classes and error codes: what to throw, and what a client sees.
- Scope and registries: the server's registries, from inside a call.
Server and configuration
How a server is put together and configured, across decorators:
| Page | Covers |
|---|---|
| Server overview | Every page in this section, grouped, and which page answers which task |
| Apps, discovery and splitting | Composing a server from apps, what clients discover, and serving apps separately |
| Flows and stages | Every flow FrontMCP runs for a request, and the stages hooks attach to |
| Loading apps from npm (ESM) | App.esm(): apps loaded from a registry at run time |
| Remote servers | Another MCP server mounted as an app |
| Configuration files | Config files and every environment variable FrontMCP reads |
| Logging | The server's own logs, levels and transports |
| Observability and telemetry | Tracing, metrics and health endpoints |
| Environment awareness | Capabilities that depend on the runtime and environment |
Authentication
How a server authenticates MCP clients, and decides what each caller may do:
| Page | Covers |
|---|---|
| Authentication overview | Every page in this section, grouped, and which page answers which task |
| Auth modes | Every mode, what it protects, and how to choose |
| Tokens and sessions | How tokens are verified, sessions, and the secrets behind them |
| Local auth | FrontMCP as its own OAuth authorization server |
| Custom login UI | The login and consent pages, and replacing them |
| Progressive auth | Asking for more access later, when a tool needs it |
| Remote and proxied auth | An external identity provider as the authorization server |
| Client ID metadata (CIMD) | Clients identified by a metadata document instead of registration |
| Authorities | Roles, permissions and rules on tools, resources, prompts, agents and skills |
| Auth in production | The checklist for running an authenticated server |
Plugins and adapters
Official packages that add behaviour to a server, or turn an API into tools:
| Page | Covers |
|---|---|
| Plugins overview | The official plugins and adapters, their packages, and how to add them to a server |
| Cache | Reusing a tool's result for identical calls, per caller or shared |
| Remember | Memory tools can read and write across calls, per session, user or tool |
| Approval | Requiring the user's approval before a tool runs |
| Feature flags | Turning tools, resources and prompts on and off with flags |
| CodeCall | Letting the model search many tools and call them from a short script |
| Skilled OpenAPI | Serving a REST API as a few skills instead of one tool per endpoint |
| OpenAPI adapter | Every operation in an OpenAPI spec as a tool |
Tool UI and React
Widgets a tool shows in the host, and React apps that talk to a server:
| Page | Covers |
|---|---|
| Tool UI | A tool's ui option, the ui://widget resource, serving modes and the widget's Content Security Policy |
| Widget components | Widgets written as React files, @frontmcp/ui hooks and components, and @frontmcp/uipack |
| Hosts and platforms | How the client is recognized, the widget's bridge, MCP Apps hosts and the OpenAI Apps SDK |
| @frontmcp/react | A server in the same process as a React app: the provider, its client, several servers, stores |
| React hooks | Calling tools, reading resources and prompts, and registering tools from components |
| React components | Generated forms, result viewers, mcpComponent, DOM resources and the router bridge |
@frontmcp/testing
End-to-end tests that start a server and call it like a client:
| Page | Covers |
|---|---|
test and the mcp client | Writing tests, the client, and the result wrappers |
| Matchers | The MCP-specific expect matchers |
| Fixtures | test.use(), and the mcp, server and auth fixtures and their lifetimes |
| Interceptors and HTTP mocking | mcp.mock, mcp.intercept, MockAPIServer and httpMock |
| Testing authentication | Tokens, clients that call as a user, and MockOAuthServer |
CLI and Nx
Creating, running and building servers, alone or in an Nx workspace:
| Page | Covers |
|---|---|
| frontmcp CLI | Every command and option: create, dev, build and its targets, test, inspector and more |
| Nx plugin | What @frontmcp/nx adds, installing it, and the workspace layout |
| Nx generators | Every generator, its options, and what it writes |
| Nx executors | Every executor, its options, and the command it runs |
| Monorepo patterns | Apps, shared libraries and server shells, and composing apps into one server |
Deployment
Building a server and running it in production:
| Page | Covers |
|---|---|
| Deployment overview | Every page in this section, grouped, and which page answers which task |
| Production build | frontmcp build, what each target writes and bundles, and how the result runs |
| Node.js and Docker | The node build on a machine, in Docker, with Redis in Compose, behind nginx, or on a Unix socket |
| Vercel | The Vercel target, what the function serves, and Vercel KV |
| AWS Lambda | The Lambda handler, what ships beside it, and the events it accepts |
| Cloudflare Workers | The Worker entry, wrangler.toml, secrets and bindings |
| Redis | The redis option, what's kept under which keys, and what happens when Redis is down |
| SQLite | Sessions, tasks and pending questions in a SQLite file on one machine |
| High availability | Several instances behind a load balancer, and what they must share |
| Health checks and metrics | /healthz, /readyz and /metrics on each runtime, and wiring them to probes |
| Security headers and transport | Headers, bind address and host checks, body limits, and exposed endpoints |
| Connecting MCP clients | Clients over Streamable HTTP, stdio or a Unix socket, and MCP Bundles |
Guides
- Rules of FrontMCP: the short list of rules that keep servers correct and safe.