From 07f70412584e1b963233e5e8bb05ca10777a011e Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 31 Aug 2026 09:04:56 -0400 Subject: [PATCH 01/13] initial pass on docs --- fern/docs.yml | 8 + .../products/mcp-generator/authentication.mdx | 39 +++++ fern/products/mcp-generator/configuration.mdx | 149 ++++++++++++++++++ .../mcp-generator/local-development.mdx | 69 ++++++++ fern/products/mcp-generator/maintaining.mdx | 61 +++++++ fern/products/mcp-generator/mcp-generator.yml | 27 ++++ .../mcp-generator/multiple-servers.mdx | 53 +++++++ fern/products/mcp-generator/overview.mdx | 38 +++++ fern/products/mcp-generator/quickstart.mdx | 119 ++++++++++++++ .../products/mcp-generator/tool-selection.mdx | 98 ++++++++++++ 10 files changed, 661 insertions(+) create mode 100644 fern/products/mcp-generator/authentication.mdx create mode 100644 fern/products/mcp-generator/configuration.mdx create mode 100644 fern/products/mcp-generator/local-development.mdx create mode 100644 fern/products/mcp-generator/maintaining.mdx create mode 100644 fern/products/mcp-generator/mcp-generator.yml create mode 100644 fern/products/mcp-generator/multiple-servers.mdx create mode 100644 fern/products/mcp-generator/overview.mdx create mode 100644 fern/products/mcp-generator/quickstart.mdx create mode 100644 fern/products/mcp-generator/tool-selection.mdx diff --git a/fern/docs.yml b/fern/docs.yml index d6dbf4896e..d06132efe3 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -51,6 +51,14 @@ products: slug: cli-generator subtitle: Generate a CLI from your API definition + # TODO(design): placeholder icon/image reused from CLI Generator — swap in real MCP Generator artwork before this ships publicly. + - display-name: MCP Generator + path: ./products/mcp-generator/mcp-generator.yml + icon: fa-regular fa-robot + image: ./images/product-switcher/product-switcher-cli-generator-light.png + slug: mcp-generator + subtitle: Generate an MCP server from your API definition + - display-name: Docs path: ./products/docs/docs.yml icon: fa-regular fa-browser diff --git a/fern/products/mcp-generator/authentication.mdx b/fern/products/mcp-generator/authentication.mdx new file mode 100644 index 0000000000..9bf436eca4 --- /dev/null +++ b/fern/products/mcp-generator/authentication.mdx @@ -0,0 +1,39 @@ +--- +title: Authentication +description: How your API's security schemes become the environment variables an MCP server reads at startup. +availability: beta +--- + +The generated MCP server doesn't need a separate auth configuration. It reads one environment variable per security scheme declared under your spec's `components.securitySchemes` and forwards it as the corresponding header on every request that needs it. + +## How the variable name is derived + +The variable's base name is the security scheme's key, upper-snake-cased. A scheme named `widgetKey` becomes `WIDGET_KEY`; a scheme named `apiToken` becomes `API_TOKEN`. + +- **HTTP Basic** schemes get two variables: `{BASE}_USERNAME` and `{BASE}_PASSWORD`. +- Every other scheme type — API key, bearer token, another HTTP scheme — gets one: `{BASE}` itself. + +A scheme named `basicAuth` with type `http`/`basic`, for example, produces `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`. + +Generation fails if a scheme's derived base isn't a legal environment variable name, or if it collides with another scheme's base or with one of the two reserved names, `BASE_URL` or `MCP_TOOLSET` — so a naming conflict surfaces at generation time instead of as a runtime mystery. + +## Always-present variables + +Every generated server also reads: + +- **`BASE_URL`** — the API's base URL. +- **`MCP_TOOLSET`** — selects which [toolset or preset](/learn/mcp-generator/get-started/configuration#presets) the server exposes at startup. Its description lists every valid value: `default`, plus whatever you've configured. + +Because these two names are reserved, no security scheme in your spec can be named `baseUrl` or `mcpToolset` — rename the scheme if it collides. + +## Where the description comes from + +Each environment variable's description comes from the security scheme's own OpenAPI `description`, when you've written one. Otherwise the generator fills in a fallback naming the credential type, such as "Credential for the widgetKey security scheme (API key)." + +## Missing credentials + +Every environment variable is optional at startup, so the server always starts even with none set. A tool call that needs a credential you haven't set fails when it's made, not before. [`fern mcp dev`](/learn/mcp-generator/get-started/local-development) checks for this up front: it detects which credentials the toolset you're running actually needs and prints the exact `export` command for anything missing, instead of leaving you to debug a 401. + +## Current limits + +OAuth client-credentials schemes aren't supported as a server's only auth source — the generated server has no token-acquisition flow to run, so generation fails outright if every security scheme your spec declares is OAuth client-credentials. Add an API key or bearer scheme for the endpoints an MCP client should reach, or [scope the toolset](/learn/mcp-generator/get-started/tool-selection) away from the ones that require it. diff --git a/fern/products/mcp-generator/configuration.mdx b/fern/products/mcp-generator/configuration.mdx new file mode 100644 index 0000000000..554a0a4b7e --- /dev/null +++ b/fern/products/mcp-generator/configuration.mdx @@ -0,0 +1,149 @@ +--- +title: Configuration reference +description: Configure MCP server generation in generators.yml — server identity, tool selection, and per-tool overrides. +availability: beta +--- + +Configure the MCP generator in `generators.yml`. Options nested under `config` are specific to the MCP generator. The rest (`output`, `github`, `audiences`, `smart-casing`, `metadata`, `api`) behave the same way as for [SDK generators](/learn/sdks/reference/generators-yml). + +```yaml title="generators.yml" {6-21} +groups: + mcp: + generators: + - name: fernapi/fern-mcp-server + version: 0.1.0 + config: + server-name: acme-public-api + instructions: >- + Refunds must stay under $100. + tools: + intent: >- + Support agents look up customers/payments, refunds under $100, no admin. + mode: static + budget: { max-tools: 40, max-tokens: 60000 } + include: + - { tag: payments, method: GET } + - { tag: customers, method: GET } + - { path-prefix: /v1/refunds } + exclude: + - { tag: internal } + overrides: + POST /v1/payments: + name: create_payment + description: "Create a payment. Amounts are in minor units." + response-fields: [id, status, amount] + output: + location: npm + package-name: "@acme/mcp" + github: + repository: acme/acme-mcp + mode: pull-request +``` + +## `config` options + + +Name shown in an MCP client's server list, and the basis for the generated package name. Defaults to the API definition's display name (kebab-cased) with `-mcp` appended. + + + +Server-level instructions passed to MCP clients on connect — the same role a system prompt plays for a model, scoped to this server. Anything the [AI-curated preset](/learn/mcp-generator/get-started/tool-selection#ai-curated-rulesets) can't express as a tool selector, like a spending limit or an escalation rule, is written here. + +```yaml +config: + instructions: "Refunds must stay under $100; escalate anything larger." +``` + + +## `tools` options + +These options live under `config.tools` in `generators.yml`. + + +Free-text description of what the MCP should let an agent do, stored verbatim. Set by the [AI-curated preset](/learn/mcp-generator/get-started/tool-selection#ai-curated-rulesets); a later `fern mcp tools --refine --ai` re-runs against this stored intent to propose rule updates once the spec changes, instead of asking you to restate what the server is for. + + + +`static` generates one tool per matched endpoint. `dynamic` collapses the toolset into three meta-tools — list, describe, invoke — covered under [dynamic mode](/learn/mcp-generator/get-started/tool-selection#presets). Set by hand or via the Refine loop; it isn't offered as a top-level preset. + + + +Overrides the default [budget verdict](/learn/mcp-generator/get-started/tool-selection#the-budget-verdict) thresholds for this group. + + + +Tool count above which `fern mcp init` and `fern mcp tools` score the toolset amber. More than 3 times this value scores red. + + +Estimated token cost above which the toolset scores amber. More than 3 times this value scores red. + + + + +Endpoints to expose as tools. Entries are OR'd together; fields within a single entry are AND'd. Omit `include` to start from every endpoint the spec exposes. + +```yaml +config: + tools: + include: + - { tag: payments, method: GET } # read-only payments + - { path-prefix: /v1/refunds } # coarse cut — the primary unit for untagged specs + - { operation-id: "payments_*" } # glob + - { endpoint: POST /v1/refunds } # a literal endpoint — the escape hatch +``` + +Each entry supports `tag`, `method`, `path-prefix`, `operation-id` (glob), and `endpoint` (a literal `METHOD /path`). Prefer the others over `endpoint` so a selection keeps matching as the spec evolves instead of freezing a list of paths. + + + +Endpoints to drop from the resolved toolset, using the same selector shape as `include`. `exclude` always wins over `include`. + +```yaml +config: + tools: + exclude: + - { tag: internal } + - { method: DELETE } +``` + + + +Per-tool polish, keyed by `METHOD /path`. + + + +Overrides the generated tool name. + + +Overrides the generated tool description. + + +Overrides the generated `readOnlyHint` MCP annotation. + + +Overrides the generated `destructiveHint` MCP annotation. + + +Restricts the tool's response to the named fields, dropping the rest before it reaches the agent. The [Refine loop](/learn/mcp-generator/get-started/tool-selection#refining-an-over-budget-toolset) writes this automatically when you project down an oversized response. + + +Marks the tool deprecated in its description instead of removing it — the migration path for a [published server](/learn/mcp-generator/get-started/maintaining#breaking-change-handling) when removing the tool outright would break existing agent integrations. + + + + +Named subsets of the group's resolved toolset, using the same selector schema as `include`/`exclude`. A client can connect to one preset instead of the whole server, and each preset gets its own verdict in `fern mcp tools`. + +```yaml +config: + tools: + presets: + read-only: + include: [{ method: GET }] + support: + intent: "support agents: lookups + refunds, no admin" + include: [{ tag: customers }, { tag: payments, method: GET }] +``` + +A preset defined here is the same object the dashboard's preset picker edits — changing one updates the other. + diff --git a/fern/products/mcp-generator/local-development.mdx b/fern/products/mcp-generator/local-development.mdx new file mode 100644 index 0000000000..3e749b663c --- /dev/null +++ b/fern/products/mcp-generator/local-development.mdx @@ -0,0 +1,69 @@ +--- +title: Local development +description: Build, inspect, and connect a generated MCP server to Claude, Cursor, or Codex. +availability: beta +--- + +## Run the inspector + +```bash +fern mcp dev --group mcp +``` + +`fern mcp dev` builds the group's server and attaches the [MCP inspector](https://modelcontextprotocol.io/legacy/tools/inspector), so you can call tools directly and check their input schemas and responses before wiring up a real client. If the toolset you're running needs a credential you haven't [set](/learn/mcp-generator/get-started/authentication), it prints the exact `export` command instead of starting a server where every call fails. + +## Build and run manually + +Every generated project also builds and runs as a standalone Node package, without the inspector: + +```bash +cd path/to/generated/mcp +npm run setup # installs dependencies and builds +npm start # runs the server over stdio +``` + +Node 20 or later is required. + +## Connect a client + +```bash +fern mcp install --local --group mcp +``` + +This wires the generated server into your local Claude, Cursor, or Codex configuration, pointing at the built `dist/index.js` and filling in the environment variables it needs. + +To wire it up by hand instead, every generated project's README includes the client config as JSON: + +```json +{ + "mcpServers": { + "acme-public-api": { + "command": "node", + "args": ["/absolute/path/to/dist/index.js"], + "env": { + "WIDGET_KEY": "", + "BASE_URL": "" + } + } + } +} +``` + +and, for Claude Code specifically, a ready-to-run install command: + +```bash +claude mcp add acme-public-api --env WIDGET_KEY= --env BASE_URL= -- node "/absolute/path/to/dist/index.js" +``` + +The client starts the server itself over stdio the first time it needs it — there's no separate process to keep running or port to open. + +## Next steps + + + + Regenerate on spec changes and catch breaking tool changes before you publish. + + + Generate separate MCP servers for different audiences from one spec. + + diff --git a/fern/products/mcp-generator/maintaining.mdx b/fern/products/mcp-generator/maintaining.mdx new file mode 100644 index 0000000000..80cccec45a --- /dev/null +++ b/fern/products/mcp-generator/maintaining.mdx @@ -0,0 +1,61 @@ +--- +title: Maintaining MCP servers +description: Regenerate on spec changes, catch breaking tool changes before you publish, and keep a published server's toolset stable. +availability: beta +--- + +Maintaining a generated MCP server follows the same loop as an SDK — edit config, regenerate — with a few commands on top for a surface an SDK doesn't have: a live toolset that downstream agents depend on staying stable. + +| Command | What it does | +|---|---| +| `fern mcp list` | Table of every configured MCP group: server name, presets, tool count, token estimate, output target, and toolset overlaps with other groups. | +| `fern mcp tools [--group g] [--preset p]` | Resolved toolset for a group, with per-tool token cost, the [budget verdict](/learn/mcp-generator/get-started/tool-selection#the-budget-verdict), and a quality lint (missing or derived-from-junk descriptions, tool name collisions, ambiguous near-duplicate tools, oversized responses). `--refine` opens the mutation loop; `--diff` compares the resolved toolset against `tools.lock`. | +| `fern generate --group g` | Regenerates the server from the current config and spec, same as any other generator. | +| `fern generator upgrade` | Upgrades the pinned generator version, same as for SDKs. | +| `fern check` | Validates config, including the [MCP-specific rules](#fern-check-rules). | + +## `tools.lock` + +`fern generate` writes a `tools.lock` file next to `generators.yml` — the resolved tool names, input schema hashes, and token costs for that group, at that generation. It's the baseline `fern mcp tools --diff` compares against, and the artifact that makes a breaking-change classification reviewable in a pull request alongside the config change that caused it. + +## Breaking-change handling + +A renamed or removed tool breaks any agent already integrated against it — a worse failure than a breaking SDK change, because nobody recompiles an agent's tool list. `fern mcp tools --diff` classifies every delta against `tools.lock`: + +- **Additive** — a new tool, or a longer/clarified description. +- **Breaking** — a tool removed or renamed, a required parameter added, response fields dropped, or the server's identity changed (`server-name` or package name, on a group that's already published). + +A breaking delta produces a `fern check` warning and a major-version-bump recommendation on publish; an additive one recommends a minor bump. This release detects and warns — it doesn't prevent a breaking change from generating or publishing. + +To retire a tool without breaking existing integrations immediately, mark it deprecated instead of removing it: + +```yaml +config: + tools: + overrides: + POST /v1/charges: + deprecated: true +``` + +This keeps the tool available but marks it deprecated in its description, giving downstream agents a migration window instead of an outage. + +## `fern check` rules + +Beyond the general SDK checks, `fern check` also flags, for MCP groups: + +- A [budget](/learn/mcp-generator/get-started/tool-selection#the-budget-verdict) warning. +- An `include`/`exclude` selector that matches nothing. +- A destructive endpoint with no `destructive` annotation override. +- A new spec endpoint matching no configured group. +- An **orphaned override** — an `overrides` entry keyed to an endpoint no longer in the spec, so a hand-written description doesn't just silently stop applying. +- A `server-name` or package rename on an already-published group, which `tools --diff` can't see on its own since it compares tools, not identity. +- A `response-fields` projection set under a generator version that doesn't support it. + +All of these print as warnings, not blockers, in CI and `--json` output. + +## Updating a server + +- **Spec changed** — regenerate; `fern mcp tools --diff` reports what moved. +- **Renaming or pruning tools** — edit `overrides` or `exclude`, then regenerate. +- **New generator version** — `fern generator upgrade`. +- **Publishing** — the same `github` and npm output blocks, and the same autorelease infrastructure, as SDK generators. diff --git a/fern/products/mcp-generator/mcp-generator.yml b/fern/products/mcp-generator/mcp-generator.yml new file mode 100644 index 0000000000..5e9fafcf20 --- /dev/null +++ b/fern/products/mcp-generator/mcp-generator.yml @@ -0,0 +1,27 @@ +navigation: + - section: Get started + contents: + - page: Overview + path: ./overview.mdx + slug: overview + - page: Quickstart + path: ./quickstart.mdx + slug: quickstart + - page: Tool selection + path: ./tool-selection.mdx + slug: tool-selection + - page: Multiple servers + path: ./multiple-servers.mdx + slug: multiple-servers + - page: Local development + path: ./local-development.mdx + slug: local-development + - page: Maintaining MCP servers + path: ./maintaining.mdx + slug: maintaining + - page: Authentication + path: ./authentication.mdx + slug: authentication + - page: Configuration reference + path: ./configuration.mdx + slug: configuration diff --git a/fern/products/mcp-generator/multiple-servers.mdx b/fern/products/mcp-generator/multiple-servers.mdx new file mode 100644 index 0000000000..166746211d --- /dev/null +++ b/fern/products/mcp-generator/multiple-servers.mdx @@ -0,0 +1,53 @@ +--- +title: Multiple servers +description: Generate separate MCP servers for different audiences from one API definition. +availability: beta +--- + +One spec can back more than one MCP server. Add another group with its own `tools` filter, and `fern generate` builds each independently: + +```yaml title="generators.yml" +groups: + mcp-payments: + generators: + - name: fernapi/fern-mcp-server + config: + server-name: acme-payments + tools: + include: [{ tag: payments }] + mcp-admin: + generators: + - name: fernapi/fern-mcp-server + config: + server-name: acme-admin + tools: + include: [{ tag: admin }] +``` + +`fern mcp init` always adds a new group; it never mutates an existing one. `fern mcp tools --refine --group ` is the mutation path for a group already written. + +Two endpoints can appear in more than one group's toolset — `fern mcp list` reports the overlap as information, not a warning. When a spec grows a new endpoint, it lands in whichever group's rules match; `fern check` warns if a new endpoint matches none of them, so nothing silently falls through the cracks. + +## Groups vs. presets + +Groups and [presets](/learn/mcp-generator/get-started/configuration#presets) both narrow a toolset, but for different reasons: + +- A **group** is a separately generated and published server — its own npm package, its own GitHub repo, its own version. +- A **preset** is a named subset of one group's toolset that a client can connect to directly — one deploy, several audiences. + +Reach for multiple groups when the audiences need different deployments (an internal admin server your public one shouldn't ship). Reach for presets when one deployment is enough and you just want to hand different clients a narrower slice of it. Small APIs typically need neither; large ones mostly need presets before they need multiple groups. + +## Splitting by audience with AI-curated + +If your intent describes more than one distinct audience, the [AI-curated preset](/learn/mcp-generator/get-started/tool-selection#ai-curated-rulesets) proposes a group per audience instead of one ruleset: + +```txt +✦ This API serves 3 distinct audiences. Proposed split: +│ acme-support (24 tools · 15k) customers, payments read + refunds +│ acme-admin (18 tools · 12k) admin tag, destructive ops — internal only +│ acme-reporting (11 tools · 9k) read-only analytics +│ +◆ Accept all / Accept some / Merge into one / Adjust… +``` + +Accepting writes each proposed group in one pass, with its own `tools.intent`. diff --git a/fern/products/mcp-generator/overview.mdx b/fern/products/mcp-generator/overview.mdx new file mode 100644 index 0000000000..f8807ed1fa --- /dev/null +++ b/fern/products/mcp-generator/overview.mdx @@ -0,0 +1,38 @@ +--- +title: MCP generator +description: "Generate an MCP server from your API definition that exposes your endpoints as tools for AI agents." +availability: beta +--- + + +The MCP generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=mcp) to get started. + + +Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a [group](/learn/mcp-generator/get-started/quickstart) like any other. + +## How it works + +The generator walks your OpenAPI operations and emits one tool per endpoint, with a name, description, and JSON Schema input derived from the operation's parameters and request body. Security schemes become environment variables the server [reads at startup](/learn/mcp-generator/get-started/authentication), and each tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, and similar) derived from its HTTP method, so an agent can reason about which calls are safe without inspecting the implementation. The output runs over stdio: an MCP client launches it as a subprocess and talks to it on stdin/stdout, so there's nothing to host or expose a port for. + +Not every operation becomes a tool. Endpoints with a non-JSON request body, or a required query parameter with a serialization style tools can't express, are skipped and recorded — with the reason — in the generated project's `metadata.json`, so you can see what got left out without reading the diff. + +## Curating the toolset + +Unlike an SDK, where exposing every endpoint is normal, an MCP server that hands an agent 300 tools is worse than one with 30 — agents spend context distinguishing similar-sounding tools, take more turns to find the right one, and are more likely to invoke something destructive by accident. [Tool selection](/learn/mcp-generator/get-started/tool-selection) is a first-class part of setting up an MCP server: `fern mcp init` diagnoses your spec's cost up front and helps you narrow it by tag, method, path, or description before you generate anything. + +## Next steps + + + + Generate an MCP server from an OpenAPI spec and connect it to an agent. + + + Curate which endpoints become tools and stay within a token budget. + + + Every field available under a group's MCP generator entry. + + + How security schemes become environment variables. + + diff --git a/fern/products/mcp-generator/quickstart.mdx b/fern/products/mcp-generator/quickstart.mdx new file mode 100644 index 0000000000..353c55bed9 --- /dev/null +++ b/fern/products/mcp-generator/quickstart.mdx @@ -0,0 +1,119 @@ +--- +title: Quickstart +description: Generate an MCP server from an OpenAPI spec and connect it to an agent in a few minutes. +availability: beta +--- + + +The MCP generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=mcp) to get started. + + +This guide generates an MCP server from an OpenAPI spec, curates its toolset, and runs it locally against an inspector. + + +Generate an MCP server from an OpenAPI specification with Fern. Follow the [MCP generator quickstart](https://buildwithfern.com/learn/mcp-generator/get-started/quickstart.md) step by step. + + +## Prerequisites + +- The Fern CLI (`npm install -g fern-api`) +- An OpenAPI 3.x spec with at least one endpoint +- Node.js 20 or later to build and run the generated server locally + + + + + + + +Any `securitySchemes` declared under your spec's `components` become the environment variables the generated server [reads at startup](/learn/mcp-generator/get-started/authentication) — the wizard doesn't ask about them. + +```bash +fern mcp init +``` + +The wizard resolves every preset against your spec up front, so each option shows its tool count and estimated token cost before you pick one: + +```txt +┌ Create an MCP server +│ +◆ Server name +│ swagger-petstore-openapi-3-0-mcp +│ +◆ Which tools should this server expose? +│ ● Read-only — lookups and searches, nothing that writes +│ 8 tools · 2k tokens — ✓ within budget +│ ○ Main resources — pet, user, store (detected from your spec) +│ 19 tools · 4k tokens — ✓ within budget +│ ○ AI-curated — Fern Agent picks tools from your description (requires fern login) +│ ○ Everything — all 19 endpoints +│ 19 tools · 4k tokens — ✓ within budget +│ +└ Wrote group "mcp" to fern/generators.yml +``` + +A preset that comes back over budget routes into a [Refine loop](/learn/mcp-generator/get-started/tool-selection#refining-an-over-budget-toolset) to narrow it before anything is written. Non-interactively, `fern mcp init -y` accepts the read-only preset and writes the group without prompting; `--name`, `--preset`, `--group`, and `--dry-run` control it from a script or CI. + + + + +```yaml title="fern/generators.yml" +groups: + mcp: + generators: + - name: fernapi/fern-mcp-server + version: 0.1.0 + output: + location: local-file-system + path: ../generated/mcp + config: + server-name: swagger-petstore-openapi-3-0-mcp + tools: + include: + - tag: pet + - tag: user + - tag: store +``` + +`tools.include` and `tools.exclude` accept tags, methods, path prefixes, operation ID globs, and literal endpoints — the [configuration reference](/learn/mcp-generator/get-started/configuration) covers every field a group can set, and [tool selection](/learn/mcp-generator/get-started/tool-selection) covers how each preset maps to these selectors. + + + + +```bash +fern generate --group mcp +``` + +Fern reads the OpenAPI spec, runs the MCP generator, and writes a TypeScript project to the output path: one file per tool, a manifest that ties tool names to their handlers, a README with client setup instructions, and a `metadata.json` summary of what was generated — and what was skipped, and why. + + + + +```bash +fern mcp dev --group mcp +``` + +This builds the server and attaches an MCP inspector so you can call tools directly before wiring up a real client. If a required credential is missing, `fern mcp dev` prints the exact `export` command instead of starting a server where every call fails. + + + + +## Next steps + + + + Curate the toolset by tag, method, path, or description. + + + Run the inspector and connect the server to Claude, Cursor, or Codex. + + + Generate separate MCP servers for different audiences from one spec. + + + Every field available under a group's MCP generator entry. + + diff --git a/fern/products/mcp-generator/tool-selection.mdx b/fern/products/mcp-generator/tool-selection.mdx new file mode 100644 index 0000000000..1826bf9c23 --- /dev/null +++ b/fern/products/mcp-generator/tool-selection.mdx @@ -0,0 +1,98 @@ +--- +title: Tool selection +description: Curate which endpoints become tools, and keep the toolset within a token budget agents can handle. +availability: beta +--- + +An MCP server that exposes 300 tools is worse than one that exposes 30: agents spend context distinguishing similar-sounding tools, take more turns to find the right one, and are more likely to call something destructive by accident. Curating the toolset — not just generating one — is the part of setting up an MCP server that an SDK never needed. + +## The budget verdict + +`fern mcp init` and `fern mcp tools` score every toolset against two independent thresholds — tool count and estimated token cost — and report the worse of the two: + +| Clause | Green | Amber | Red | +|---|---|---|---| +| Tool count | ≤ 40 | 41 – 120 | > 120 | +| Token cost (estimated) | ≤ 60k | 60k – 180k | > 180k | + +Token figures are always labeled as estimates; when a cost can't be computed for a given tool, the verdict falls back to scoring tool count alone. The thresholds are configurable per group: + +```yaml title="generators.yml" +config: + tools: + budget: + max-tools: 40 + max-tokens: 60000 +``` + +An amber or red verdict doesn't block generation. Interactively, it routes into the [Refine loop](#refining-an-over-budget-toolset); in a script or CI (`--json`, non-interactive `fern mcp init -y`), it prints as a warning instead. + +## Presets + +`fern mcp init` resolves every preset against your spec up front, so each option's cost is visible before you pick one: + +- **Read-only** — every `GET` endpoint, plus read-like `POST` endpoints the wizard detects from naming conventions (`search*`, `list_*`, and similar — common for search or query operations hidden behind `POST`). When detection is ambiguous, the endpoint is excluded and the wizard tells you to review it with `fern mcp tools` rather than guessing. +- **Main resources** — one `include` entry per primary tag, with administrative and internal tags excluded. Grayed out on specs with no usable tags, where [untagged spec handling](#specs-without-tags) applies instead. +- **AI-curated** — describe what the MCP should let an agent do, and [Fern Agent](/learn/docs/fern-agent) proposes a ruleset. Requires `fern login`; falls back to the heuristic presets if you're logged out. +- **Everything** — every endpoint becomes a tool, unfiltered. + +Picking a preset writes the same declarative rules you'd write by hand — tags, methods, path prefixes, operation ID globs, or literal endpoints, detailed under [`include`](/learn/mcp-generator/get-started/configuration#include) in the configuration reference — so the toolset survives spec changes instead of freezing a list of endpoint names. + +A **dynamic mode** is also available (`tools.mode: dynamic`), which collapses the toolset into three meta-tools — list, describe, and invoke — instead of one tool per endpoint. It isn't offered as a preset: agents do measurably worse against meta-tools than direct, named tools, since tool names and descriptions carry most of the signal an agent uses to pick correctly. Reach for it only as a last resort for a spec too large to narrow any other way, or set it by hand. + +## Refining an over-budget toolset + +`fern mcp tools --refine` opens the same loop `fern mcp init` routes into automatically on an amber or red verdict. It lists the highest-cost tools with a reason, then offers to narrow the toolset, project down oversized responses, or accept the toolset as-is — re-scoring the verdict after every change: + +```txt +Verdict: 112 tools · 94k tokens — ⚠ ~3x over budget (both clauses) + +Highest-cost tools: + get_report_bundle 11k tokens oversized response schema + search_transactions 7k tokens 34 parameters + +◆ Refine? +│ ● Narrow rules… # tags, methods, path prefixes +│ ○ Filter oversized responses (project fields)… +│ ○ Switch to dynamic mode (3 list/describe/invoke meta-tools) +│ ○ Accept as-is +``` + +Narrowing writes compound selectors where they express the intent — `{ tag: reports, method: GET }` for "read-only reports" — rather than an enumerated endpoint list. Response-field projection keeps a tool but restricts its response to the fields you name, via `overrides..response-fields` in the [configuration reference](/learn/mcp-generator/get-started/configuration#overrides). "Switch to dynamic mode" writes `tools.mode: dynamic` as a stated trade-off, not a silent one. + +`--refine` mutates an existing group's config in place. `fern mcp init` always adds a new group and never mutates one — the two commands are deliberately disjoint. + +## AI-curated rulesets + +The AI-curated preset takes one free-text description and proposes a ruleset conversationally: + +```txt +◆ Describe what this MCP should let an agent do (and anything it must never touch) +│ > Let support agents look up customers and payments, issue refunds under +│ $100, never touch admin or delete anything + +✦ Proposed ruleset (exclusions first — that's the part worth reviewing): +│ exclude: +│ - { tag: admin } # "never touch admin" +│ - { method: DELETE } # "never delete anything" +│ include: +│ - { tag: customers, method: GET } +│ - { tag: payments, method: GET } +│ - { endpoint: POST /v1/refunds } +│ instructions: "Refunds must stay under $100; escalate anything larger." +│ +│ Verdict: 21 tools · 14k tokens — ✓ within budget +│ +◆ Accept / Adjust (describe the change) / Start over / Switch to manual +``` + +The proposal leads with what it excluded, since a 20-tool include list is hard to eyeball but an exclusion list is easy to verify against what you asked for. Anything the model can't express as a selector — a spending limit, an escalation rule — is written into the server's `instructions` field or a per-tool `overrides` description instead of silently dropped. The output is always the same declarative rules any other preset writes: reviewable, diffable, and safe to hand-edit afterward. Run it non-interactively with `fern mcp init --preset ai --intent "support agents, refunds under $100, no admin"`. + +## Specs without tags + +Many real specs have no tags, junk operation IDs, and no descriptions — often the specs that need curation the most. When a spec has no usable tags: + +- The diagnosis says so up front: `312 endpoints · no tags — grouping by path prefix`. +- Refine's narrowing offers path prefixes (`/v1/payments/*`) instead of tags. +- The AI-curated preset is promoted as the primary option, since inferring groupings and writing tool names and descriptions is where it earns its keep on a spec like this. +- `fern mcp tools` flags tool names derived from junk operation IDs (`post_v1_pmt_x2`) so you know where to add an `overrides` entry. From c92e40b4a60dd34b3f234fcf805466f97dc59a67 Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 10 Sep 2026 23:15:26 +0000 Subject: [PATCH 02/13] Hide MCP generator pages behind temporary customer preview page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/mcp-generator.yml | 12 ++ .../mcp-generator/mcp-server-integration.mdx | 127 ++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 fern/products/mcp-generator/mcp-server-integration.mdx diff --git a/fern/products/mcp-generator/mcp-generator.yml b/fern/products/mcp-generator/mcp-generator.yml index 5e9fafcf20..2d8618564b 100644 --- a/fern/products/mcp-generator/mcp-generator.yml +++ b/fern/products/mcp-generator/mcp-generator.yml @@ -1,27 +1,39 @@ navigation: - section: Get started contents: + # TODO: temporary customer preview page; remove once the pages below are unhidden. + - page: MCP server integration + path: ./mcp-server-integration.mdx + slug: mcp-server-integration - page: Overview path: ./overview.mdx slug: overview + hidden: true - page: Quickstart path: ./quickstart.mdx slug: quickstart + hidden: true - page: Tool selection path: ./tool-selection.mdx slug: tool-selection + hidden: true - page: Multiple servers path: ./multiple-servers.mdx slug: multiple-servers + hidden: true - page: Local development path: ./local-development.mdx slug: local-development + hidden: true - page: Maintaining MCP servers path: ./maintaining.mdx slug: maintaining + hidden: true - page: Authentication path: ./authentication.mdx slug: authentication + hidden: true - page: Configuration reference path: ./configuration.mdx slug: configuration + hidden: true diff --git a/fern/products/mcp-generator/mcp-server-integration.mdx b/fern/products/mcp-generator/mcp-server-integration.mdx new file mode 100644 index 0000000000..3904212df5 --- /dev/null +++ b/fern/products/mcp-generator/mcp-server-integration.mdx @@ -0,0 +1,127 @@ +--- +title: MCP server integration +description: Provision, configure, refine, and monitor Model Context Protocol servers from the Fern dashboard. +availability: beta +--- + + +This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. + + +Model Context Protocol (MCP) servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. + +## Provisioning a server + +When you initialize a new server instance from the dashboard, Fern offers two onboarding paths. + + + + The fastest path uses your development agent to automate setup locally. + + + + Copy the prompt template from the onboarding view. + + ```txt + You are an expert developer assistant tasked with configuring a Fern Model Context Protocol (MCP) server. + + Walk through the required setup steps locally or directly initialize a valid `generators.yml` configuration file targeting the user's workspace environment. Ensure proper syntax rules are enforced. + ``` + + + Paste the prompt into your agent workspace to automate CLI execution or generate your project configuration. + + + + + + Use the dashboard configuration wizard to work directly in the UI, or if you don't have a local environment set up. + + + + If a documentation repository is already linked to your Fern organization, the dashboard detects and lists your available OpenAPI specifications. Without a linked repo, upload a spec file or supply a remote URL. + + + Selecting a spec triggers a background task that pushes a configuration change to your linked repository as a pull request. Organizations without a linked code provider get a platform-managed repository, so setup is never blocked. + + + + + +## Core file schemas + +### `generators.yml` + +The behavior, versioning, and endpoint rules of your MCP server are governed by this file: + +```yaml title="fern/generators.yml" +- name: fern-mcp + version: 0.0.1 + config: + spec: ./openapi.yml +``` + +### Environment variables + +To route local evaluation loops through isolated remote orchestration in test environments, set: + +```bash +export FERN_REMOTE_GENERATION_URL=https://fake-endpoint.october.internal +``` + +### CLI tooling + +All structural checks, schema compilation, and generation loops run under one command group: + +```bash +fern generate mcp +``` + +## Lifecycle and validation + +Once an MCP configuration is synchronized, the dashboard gives you administrative control over live runtime environments. + + + + Pause or resume public endpoint availability to lock down access or handle upstream API refactors. + + + Run live endpoint validation queries with the embedded Fern Agent console. No customer-owned production model tokens are consumed. + + + Get notified when your OpenAPI spec deviates from the running schema, or when endpoint counts cross operational limits. + + + +## Tool refinement and token analysis + +The refinement panel gives you structural control over individual tools derived from your spec. Rename tool keys, rewrite descriptions for client-agent visibility, or toggle deprecation flags from the same panel. + +- **AI refining prompts**: run natural language refinement queries in the split-panel configuration workspace to isolate broad functional domains (for example, "Read-only main resources") without manual file-by-file overrides. +- **Token footprint metrics**: see absolute token consumption against comparative engine scales (Claude Code, Codex, and others) to optimize client performance. + +## Runtime analytics + +The monitoring panel processes telemetry from active server instances into a few concrete views: + +| Metric | What it tells you | +|---|---| +| Execution performance profiles | Query frequency, throughput, and engagement, tracked tool-by-tool | +| Schema boundary analytics | Processing exceptions and code faults by root cause, prioritizing schema validation errors | +| Dead-code identification | Underutilized tools in the live profile, so you can trim client context overhead | + +## Public landings and branded access hubs + +Fern abstracts away client setup by generating end-user connectivity portals for you. + + + + Modular connection blocks are deployed into your existing public docs via automated pull requests, complete with tabbed copy layouts, code definitions, and implementation guides. + + + Public configuration targets are generated and tied directly to your platform server strings. + + + Connection interfaces inherit your organization's logos and color palette from your active documentation config. + + From dc81761d7d371c8dfa17e4224aba5274e4f20d24 Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 10 Sep 2026 23:50:34 +0000 Subject: [PATCH 03/13] Add overview intro to MCP server integration preview page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/mcp-server-integration.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/fern/products/mcp-generator/mcp-server-integration.mdx b/fern/products/mcp-generator/mcp-server-integration.mdx index 3904212df5..a1420879a3 100644 --- a/fern/products/mcp-generator/mcp-server-integration.mdx +++ b/fern/products/mcp-generator/mcp-server-integration.mdx @@ -8,7 +8,9 @@ availability: beta This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. -Model Context Protocol (MCP) servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. +Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other. + +MCP servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. ## Provisioning a server From 595b7c6d662e8aee5f3792960ac019a53652b172 Mon Sep 17 00:00:00 2001 From: Nermina Date: Thu, 10 Sep 2026 23:58:27 +0000 Subject: [PATCH 04/13] Use verb headings on MCP server integration page Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../mcp-generator/mcp-server-integration.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/fern/products/mcp-generator/mcp-server-integration.mdx b/fern/products/mcp-generator/mcp-server-integration.mdx index a1420879a3..588f20e172 100644 --- a/fern/products/mcp-generator/mcp-server-integration.mdx +++ b/fern/products/mcp-generator/mcp-server-integration.mdx @@ -12,7 +12,7 @@ Fern's MCP generator turns your API definition into a [Model Context Protocol](h MCP servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. -## Provisioning a server +## Provision a server When you initialize a new server instance from the dashboard, Fern offers two onboarding paths. @@ -50,9 +50,9 @@ When you initialize a new server instance from the dashboard, Fern offers two on -## Core file schemas +## Configure core files -### `generators.yml` +### Define `generators.yml` The behavior, versioning, and endpoint rules of your MCP server are governed by this file: @@ -63,7 +63,7 @@ The behavior, versioning, and endpoint rules of your MCP server are governed by spec: ./openapi.yml ``` -### Environment variables +### Set environment variables To route local evaluation loops through isolated remote orchestration in test environments, set: @@ -71,7 +71,7 @@ To route local evaluation loops through isolated remote orchestration in test en export FERN_REMOTE_GENERATION_URL=https://fake-endpoint.october.internal ``` -### CLI tooling +### Run CLI tooling All structural checks, schema compilation, and generation loops run under one command group: @@ -79,7 +79,7 @@ All structural checks, schema compilation, and generation loops run under one co fern generate mcp ``` -## Lifecycle and validation +## Manage the server lifecycle Once an MCP configuration is synchronized, the dashboard gives you administrative control over live runtime environments. @@ -95,14 +95,14 @@ Once an MCP configuration is synchronized, the dashboard gives you administrativ -## Tool refinement and token analysis +## Refine tools and analyze tokens The refinement panel gives you structural control over individual tools derived from your spec. Rename tool keys, rewrite descriptions for client-agent visibility, or toggle deprecation flags from the same panel. - **AI refining prompts**: run natural language refinement queries in the split-panel configuration workspace to isolate broad functional domains (for example, "Read-only main resources") without manual file-by-file overrides. - **Token footprint metrics**: see absolute token consumption against comparative engine scales (Claude Code, Codex, and others) to optimize client performance. -## Runtime analytics +## Monitor runtime analytics The monitoring panel processes telemetry from active server instances into a few concrete views: @@ -112,7 +112,7 @@ The monitoring panel processes telemetry from active server instances into a few | Schema boundary analytics | Processing exceptions and code faults by root cause, prioritizing schema validation errors | | Dead-code identification | Underutilized tools in the live profile, so you can trim client context overhead | -## Public landings and branded access hubs +## Publish branded access hubs Fern abstracts away client setup by generating end-user connectivity portals for you. From 18c8b6f625acea45ac7d5e4a9d6da769817542df Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 00:00:19 +0000 Subject: [PATCH 05/13] Rename preview page to Generate MCP servers with Fern Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- ...{mcp-server-integration.mdx => generate-mcp-servers.mdx} | 4 ++-- fern/products/mcp-generator/mcp-generator.yml | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) rename fern/products/mcp-generator/{mcp-server-integration.mdx => generate-mcp-servers.mdx} (97%) diff --git a/fern/products/mcp-generator/mcp-server-integration.mdx b/fern/products/mcp-generator/generate-mcp-servers.mdx similarity index 97% rename from fern/products/mcp-generator/mcp-server-integration.mdx rename to fern/products/mcp-generator/generate-mcp-servers.mdx index 588f20e172..0eeb9c1675 100644 --- a/fern/products/mcp-generator/mcp-server-integration.mdx +++ b/fern/products/mcp-generator/generate-mcp-servers.mdx @@ -1,6 +1,6 @@ --- -title: MCP server integration -description: Provision, configure, refine, and monitor Model Context Protocol servers from the Fern dashboard. +title: Generate MCP servers with Fern +description: Generate, configure, refine, and monitor Model Context Protocol servers from your API definition with Fern. availability: beta --- diff --git a/fern/products/mcp-generator/mcp-generator.yml b/fern/products/mcp-generator/mcp-generator.yml index 2d8618564b..d3fff34171 100644 --- a/fern/products/mcp-generator/mcp-generator.yml +++ b/fern/products/mcp-generator/mcp-generator.yml @@ -2,9 +2,9 @@ navigation: - section: Get started contents: # TODO: temporary customer preview page; remove once the pages below are unhidden. - - page: MCP server integration - path: ./mcp-server-integration.mdx - slug: mcp-server-integration + - page: Generate MCP servers with Fern + path: ./generate-mcp-servers.mdx + slug: generate-mcp-servers - page: Overview path: ./overview.mdx slug: overview From 58541be3b8093f2575852dfefaaf2caddda0cb60 Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 00:01:54 +0000 Subject: [PATCH 06/13] Use bulleted list for branded access hubs section Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../mcp-generator/generate-mcp-servers.mdx | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/fern/products/mcp-generator/generate-mcp-servers.mdx b/fern/products/mcp-generator/generate-mcp-servers.mdx index 0eeb9c1675..e4963d856c 100644 --- a/fern/products/mcp-generator/generate-mcp-servers.mdx +++ b/fern/products/mcp-generator/generate-mcp-servers.mdx @@ -116,14 +116,6 @@ The monitoring panel processes telemetry from active server instances into a few Fern abstracts away client setup by generating end-user connectivity portals for you. - - - Modular connection blocks are deployed into your existing public docs via automated pull requests, complete with tabbed copy layouts, code definitions, and implementation guides. - - - Public configuration targets are generated and tied directly to your platform server strings. - - - Connection interfaces inherit your organization's logos and color palette from your active documentation config. - - +- **Automated page injection**: modular connection blocks are deployed into your existing public docs via automated pull requests, complete with tabbed copy layouts, code definitions, and implementation guides. +- **Branded portals**: public configuration targets are generated and tied directly to your platform server strings. +- **Theme synchronization**: connection interfaces inherit your organization's logos and color palette from your active documentation config. From cef5f994f5e2c28ae89587d96f4193f9c768989a Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 03:48:01 +0000 Subject: [PATCH 07/13] Split customer preview page into overview, quickstart, and manage pages Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../mcp-generator/generate-mcp-servers.mdx | 121 ------------------ fern/products/mcp-generator/mcp-generator.yml | 14 +- .../products/mcp-generator/preview/manage.mdx | 50 ++++++++ .../mcp-generator/preview/overview.mdx | 22 ++++ .../mcp-generator/preview/quickstart.mdx | 78 +++++++++++ 5 files changed, 160 insertions(+), 125 deletions(-) delete mode 100644 fern/products/mcp-generator/generate-mcp-servers.mdx create mode 100644 fern/products/mcp-generator/preview/manage.mdx create mode 100644 fern/products/mcp-generator/preview/overview.mdx create mode 100644 fern/products/mcp-generator/preview/quickstart.mdx diff --git a/fern/products/mcp-generator/generate-mcp-servers.mdx b/fern/products/mcp-generator/generate-mcp-servers.mdx deleted file mode 100644 index e4963d856c..0000000000 --- a/fern/products/mcp-generator/generate-mcp-servers.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Generate MCP servers with Fern -description: Generate, configure, refine, and monitor Model Context Protocol servers from your API definition with Fern. -availability: beta ---- - - -This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. - - -Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other. - -MCP servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. - -## Provision a server - -When you initialize a new server instance from the dashboard, Fern offers two onboarding paths. - - - - The fastest path uses your development agent to automate setup locally. - - - - Copy the prompt template from the onboarding view. - - ```txt - You are an expert developer assistant tasked with configuring a Fern Model Context Protocol (MCP) server. - - Walk through the required setup steps locally or directly initialize a valid `generators.yml` configuration file targeting the user's workspace environment. Ensure proper syntax rules are enforced. - ``` - - - Paste the prompt into your agent workspace to automate CLI execution or generate your project configuration. - - - - - - Use the dashboard configuration wizard to work directly in the UI, or if you don't have a local environment set up. - - - - If a documentation repository is already linked to your Fern organization, the dashboard detects and lists your available OpenAPI specifications. Without a linked repo, upload a spec file or supply a remote URL. - - - Selecting a spec triggers a background task that pushes a configuration change to your linked repository as a pull request. Organizations without a linked code provider get a platform-managed repository, so setup is never blocked. - - - - - -## Configure core files - -### Define `generators.yml` - -The behavior, versioning, and endpoint rules of your MCP server are governed by this file: - -```yaml title="fern/generators.yml" -- name: fern-mcp - version: 0.0.1 - config: - spec: ./openapi.yml -``` - -### Set environment variables - -To route local evaluation loops through isolated remote orchestration in test environments, set: - -```bash -export FERN_REMOTE_GENERATION_URL=https://fake-endpoint.october.internal -``` - -### Run CLI tooling - -All structural checks, schema compilation, and generation loops run under one command group: - -```bash -fern generate mcp -``` - -## Manage the server lifecycle - -Once an MCP configuration is synchronized, the dashboard gives you administrative control over live runtime environments. - - - - Pause or resume public endpoint availability to lock down access or handle upstream API refactors. - - - Run live endpoint validation queries with the embedded Fern Agent console. No customer-owned production model tokens are consumed. - - - Get notified when your OpenAPI spec deviates from the running schema, or when endpoint counts cross operational limits. - - - -## Refine tools and analyze tokens - -The refinement panel gives you structural control over individual tools derived from your spec. Rename tool keys, rewrite descriptions for client-agent visibility, or toggle deprecation flags from the same panel. - -- **AI refining prompts**: run natural language refinement queries in the split-panel configuration workspace to isolate broad functional domains (for example, "Read-only main resources") without manual file-by-file overrides. -- **Token footprint metrics**: see absolute token consumption against comparative engine scales (Claude Code, Codex, and others) to optimize client performance. - -## Monitor runtime analytics - -The monitoring panel processes telemetry from active server instances into a few concrete views: - -| Metric | What it tells you | -|---|---| -| Execution performance profiles | Query frequency, throughput, and engagement, tracked tool-by-tool | -| Schema boundary analytics | Processing exceptions and code faults by root cause, prioritizing schema validation errors | -| Dead-code identification | Underutilized tools in the live profile, so you can trim client context overhead | - -## Publish branded access hubs - -Fern abstracts away client setup by generating end-user connectivity portals for you. - -- **Automated page injection**: modular connection blocks are deployed into your existing public docs via automated pull requests, complete with tabbed copy layouts, code definitions, and implementation guides. -- **Branded portals**: public configuration targets are generated and tied directly to your platform server strings. -- **Theme synchronization**: connection interfaces inherit your organization's logos and color palette from your active documentation config. diff --git a/fern/products/mcp-generator/mcp-generator.yml b/fern/products/mcp-generator/mcp-generator.yml index d3fff34171..852e3489e5 100644 --- a/fern/products/mcp-generator/mcp-generator.yml +++ b/fern/products/mcp-generator/mcp-generator.yml @@ -1,10 +1,16 @@ navigation: - section: Get started contents: - # TODO: temporary customer preview page; remove once the pages below are unhidden. - - page: Generate MCP servers with Fern - path: ./generate-mcp-servers.mdx - slug: generate-mcp-servers + # TODO: temporary customer preview pages; remove once the hidden pages below are unhidden. + - page: Overview + path: ./preview/overview.mdx + slug: preview-overview + - page: Quickstart + path: ./preview/quickstart.mdx + slug: preview-quickstart + - page: Manage MCP servers + path: ./preview/manage.mdx + slug: preview-manage - page: Overview path: ./overview.mdx slug: overview diff --git a/fern/products/mcp-generator/preview/manage.mdx b/fern/products/mcp-generator/preview/manage.mdx new file mode 100644 index 0000000000..2bcb698370 --- /dev/null +++ b/fern/products/mcp-generator/preview/manage.mdx @@ -0,0 +1,50 @@ +--- +title: Manage MCP servers +description: Control the lifecycle of generated MCP servers, refine their tools, monitor runtime analytics, and publish branded access hubs. +availability: beta +--- + + +This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. + + +Once an MCP configuration is synchronized, the dashboard gives you administrative control over live runtime environments: pause or resume servers, refine the toolset agents see, inspect telemetry, and publish end-user connection portals. This page assumes you have already [provisioned a server](/learn/mcp-generator/get-started/preview-quickstart). + +## Manage the server lifecycle + + + + Pause or resume public endpoint availability to lock down access or handle upstream API refactors. + + + Run live endpoint validation queries with the embedded Fern Agent console. No customer-owned production model tokens are consumed. + + + Get notified when your OpenAPI spec deviates from the running schema, or when endpoint counts cross operational limits. + + + +## Refine tools and analyze tokens + +The refinement panel gives you structural control over individual tools derived from your spec. Rename tool keys, rewrite descriptions for client-agent visibility, or toggle deprecation flags from the same panel. + +- **AI refining prompts**: run natural language refinement queries in the split-panel configuration workspace to isolate broad functional domains (for example, "Read-only main resources") without manual file-by-file overrides. +- **Token footprint metrics**: see absolute token consumption against comparative engine scales (Claude Code, Codex, and others) to optimize client performance. + +## Monitor runtime analytics + +The monitoring panel processes telemetry from active server instances into a few concrete views: + +| Metric | What it tells you | +|---|---| +| Execution performance profiles | Query frequency, throughput, and engagement, tracked tool-by-tool | +| Schema boundary analytics | Processing exceptions and code faults by root cause, prioritizing schema validation errors | +| Dead-code identification | Underutilized tools in the live profile, so you can trim client context overhead | + +## Publish branded access hubs + +Fern abstracts away client setup by generating end-user connectivity portals for you. + +- **Automated page injection**: modular connection blocks are deployed into your existing public docs via automated pull requests, complete with tabbed copy layouts, code definitions, and implementation guides. +- **Branded portals**: public configuration targets are generated and tied directly to your platform server strings. +- **Theme synchronization**: connection interfaces inherit your organization's logos and color palette from your active documentation config. diff --git a/fern/products/mcp-generator/preview/overview.mdx b/fern/products/mcp-generator/preview/overview.mdx new file mode 100644 index 0000000000..b33323e79a --- /dev/null +++ b/fern/products/mcp-generator/preview/overview.mdx @@ -0,0 +1,22 @@ +--- +title: Generate MCP servers with Fern +description: Generate, configure, refine, and monitor Model Context Protocol servers from your API definition with Fern. +availability: beta +--- + + +This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. + + +Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other. + +MCP servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. + + + + Provision a server from the dashboard and configure `generators.yml`, environment variables, and CLI tooling. + + + Control the server lifecycle, refine tools, monitor runtime analytics, and publish branded access hubs. + + diff --git a/fern/products/mcp-generator/preview/quickstart.mdx b/fern/products/mcp-generator/preview/quickstart.mdx new file mode 100644 index 0000000000..1ded9d899a --- /dev/null +++ b/fern/products/mcp-generator/preview/quickstart.mdx @@ -0,0 +1,78 @@ +--- +title: Quickstart +description: Provision an MCP server from the Fern dashboard and configure its core files. +availability: beta +--- + + +This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. + + +This guide provisions a new MCP server from the dashboard and configures the files that govern how Fern generates it. Once the server is generated, the [manage guide](/learn/mcp-generator/get-started/preview-manage) covers the lifecycle controls, tool refinement, and analytics the dashboard provides. + +## Provision a server + +When you initialize a new server instance from the dashboard, Fern offers two onboarding paths. + + + + The fastest path uses your development agent to automate setup locally. + + + + Copy the prompt template from the onboarding view. + + ```txt + You are an expert developer assistant tasked with configuring a Fern Model Context Protocol (MCP) server. + + Walk through the required setup steps locally or directly initialize a valid `generators.yml` configuration file targeting the user's workspace environment. Ensure proper syntax rules are enforced. + ``` + + + Paste the prompt into your agent workspace to automate CLI execution or generate your project configuration. + + + + + + Use the dashboard configuration wizard to work directly in the UI, or if you don't have a local environment set up. + + + + If a documentation repository is already linked to your Fern organization, the dashboard detects and lists your available OpenAPI specifications. Without a linked repo, upload a spec file or supply a remote URL. + + + Selecting a spec triggers a background task that pushes a configuration change to your linked repository as a pull request. Organizations without a linked code provider get a platform-managed repository, so setup is never blocked. + + + + + +## Configure core files + +### Define `generators.yml` + +The behavior, versioning, and endpoint rules of your MCP server are governed by this file: + +```yaml title="fern/generators.yml" +- name: fern-mcp + version: 0.0.1 + config: + spec: ./openapi.yml +``` + +### Set environment variables + +To route local evaluation loops through isolated remote orchestration in test environments, set: + +```bash +export FERN_REMOTE_GENERATION_URL=https://fake-endpoint.october.internal +``` + +### Run CLI tooling + +All structural checks, schema compilation, and generation loops run under one command group: + +```bash +fern generate mcp +``` From fc1ead7af09ab8593e4ef69aea48af468161921f Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 03:51:37 +0000 Subject: [PATCH 08/13] Reword dashboard access sentence in preview overview Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/mcp-generator/preview/overview.mdx b/fern/products/mcp-generator/preview/overview.mdx index b33323e79a..05f01ad0a7 100644 --- a/fern/products/mcp-generator/preview/overview.mdx +++ b/fern/products/mcp-generator/preview/overview.mdx @@ -10,7 +10,7 @@ This page is a preview of a feature in development. Names, commands, and configu Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other. -MCP servers are a distinct product layer in the dashboard sidebar. From here, admins manage an organization-wide registry of isolated MCP server deployments, each tailored to a different runtime or tooling environment. +Access your MCP servers from the **MCP servers** section of the [Fern dashboard](https://dashboard.buildwithfern.com/). Admins can provision new servers, configure and refine each server's toolset, pause or resume deployments, and monitor runtime analytics across the organization. From 32da8ce0218b1ca141cec000c8f2d5e91c36a21e Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 03:57:08 +0000 Subject: [PATCH 09/13] Add New MCP Server step to preview quickstart Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/mcp-generator/preview/quickstart.mdx b/fern/products/mcp-generator/preview/quickstart.mdx index 1ded9d899a..a04e07c05c 100644 --- a/fern/products/mcp-generator/preview/quickstart.mdx +++ b/fern/products/mcp-generator/preview/quickstart.mdx @@ -12,7 +12,7 @@ This guide provisions a new MCP server from the dashboard and configures the fil ## Provision a server -When you initialize a new server instance from the dashboard, Fern offers two onboarding paths. +In the [Fern dashboard](https://dashboard.buildwithfern.com/), click **New MCP Server**. Fern offers two onboarding paths. From 3ec61994986254cba641fba8990b40d6b9089b81 Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 03:57:17 +0000 Subject: [PATCH 10/13] Use select per Vale UIVerbs rule Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/mcp-generator/preview/quickstart.mdx b/fern/products/mcp-generator/preview/quickstart.mdx index a04e07c05c..110ff5f38f 100644 --- a/fern/products/mcp-generator/preview/quickstart.mdx +++ b/fern/products/mcp-generator/preview/quickstart.mdx @@ -12,7 +12,7 @@ This guide provisions a new MCP server from the dashboard and configures the fil ## Provision a server -In the [Fern dashboard](https://dashboard.buildwithfern.com/), click **New MCP Server**. Fern offers two onboarding paths. +In the [Fern dashboard](https://dashboard.buildwithfern.com/), select **New MCP Server**. Fern offers two onboarding paths. From 26186e67be1b5d48ca94b86909b274a815280887 Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 04:04:08 +0000 Subject: [PATCH 11/13] Add MCP Servers location to quickstart step Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/overview.mdx | 2 +- fern/products/mcp-generator/preview/quickstart.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/mcp-generator/preview/overview.mdx b/fern/products/mcp-generator/preview/overview.mdx index 05f01ad0a7..4bb5798312 100644 --- a/fern/products/mcp-generator/preview/overview.mdx +++ b/fern/products/mcp-generator/preview/overview.mdx @@ -10,7 +10,7 @@ This page is a preview of a feature in development. Names, commands, and configu Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other. -Access your MCP servers from the **MCP servers** section of the [Fern dashboard](https://dashboard.buildwithfern.com/). Admins can provision new servers, configure and refine each server's toolset, pause or resume deployments, and monitor runtime analytics across the organization. +Access your MCP servers from the **MCP Servers** section of the [Fern dashboard](https://dashboard.buildwithfern.com/). Admins can provision new servers, configure and refine each server's toolset, pause or resume deployments, and monitor runtime analytics across the organization. diff --git a/fern/products/mcp-generator/preview/quickstart.mdx b/fern/products/mcp-generator/preview/quickstart.mdx index 110ff5f38f..b63c6554c1 100644 --- a/fern/products/mcp-generator/preview/quickstart.mdx +++ b/fern/products/mcp-generator/preview/quickstart.mdx @@ -12,7 +12,7 @@ This guide provisions a new MCP server from the dashboard and configures the fil ## Provision a server -In the [Fern dashboard](https://dashboard.buildwithfern.com/), select **New MCP Server**. Fern offers two onboarding paths. +In the [Fern dashboard](https://dashboard.buildwithfern.com/), under **MCP Servers**, select **New MCP Server**. Fern offers two onboarding paths. From 576ed13c8801cea17bbed3a5e65fd937e54bcc2c Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 04:16:19 +0000 Subject: [PATCH 12/13] Use Prompt component for onboarding prompt in preview quickstart Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/quickstart.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/fern/products/mcp-generator/preview/quickstart.mdx b/fern/products/mcp-generator/preview/quickstart.mdx index b63c6554c1..cd623dd894 100644 --- a/fern/products/mcp-generator/preview/quickstart.mdx +++ b/fern/products/mcp-generator/preview/quickstart.mdx @@ -22,11 +22,12 @@ In the [Fern dashboard](https://dashboard.buildwithfern.com/), under **MCP Serve Copy the prompt template from the onboarding view. - ```txt - You are an expert developer assistant tasked with configuring a Fern Model Context Protocol (MCP) server. - - Walk through the required setup steps locally or directly initialize a valid `generators.yml` configuration file targeting the user's workspace environment. Ensure proper syntax rules are enforced. - ``` + + You are an expert developer assistant tasked with configuring a Fern Model Context Protocol (MCP) server. Walk through the required setup steps locally or directly initialize a valid `generators.yml` configuration file targeting the user's workspace environment. Ensure proper syntax rules are enforced. + Paste the prompt into your agent workspace to automate CLI execution or generate your project configuration. From 3a602afb1c448ee5177b2aa34212cd5b4bc1dd6a Mon Sep 17 00:00:00 2001 From: Nermina Date: Fri, 11 Sep 2026 04:51:57 +0000 Subject: [PATCH 13/13] Expand customer preview note on overview with demo and feedback call Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/mcp-generator/preview/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/mcp-generator/preview/overview.mdx b/fern/products/mcp-generator/preview/overview.mdx index 4bb5798312..b8769fd3fd 100644 --- a/fern/products/mcp-generator/preview/overview.mdx +++ b/fern/products/mcp-generator/preview/overview.mdx @@ -5,7 +5,7 @@ availability: beta --- -This page is a preview of a feature in development. Names, commands, and configuration shown here may change before release. +The MCP server dashboard is in development and not yet generally available. This documentation gives an overview of its functionality, and Fern is excited to hear your feedback. [Book a demo](https://buildwithfern.com/book-demo?type=mcp) and a Fern engineer will walk you through the workflow for spinning up MCP servers. Fern's MCP generator turns your API definition into a [Model Context Protocol](https://modelcontextprotocol.io) server: a project where every endpoint becomes a typed tool that Claude, Cursor, and other MCP clients can call directly. It shares the same spec, `generators.yml`, and generation pipeline as your SDKs and CLI — an MCP server is just another generator output, configured as a group like any other.