diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index be13bd1b3..5b227f7df 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -14,6 +14,7 @@ hideOnThisPage: true | [`fern downgrade`](#fern-downgrade) | Move the Fern CLI version in `fern.config.json` back to an older version | | [`fern login`](#fern-login) | Login to Fern CLI via GitHub, Google, Postman, or enterprise SSO | | [`fern logout`](#fern-logout) | Log out of the Fern CLI | +| [`fern mcp install`](#fern-mcp-install) | Connect Claude Code, Cursor, or Codex to Fern's MCP server | | [`fern export`](#fern-export) | Export an OpenAPI spec for your API | | [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec | | [`fern api enrich`](#fern-api-enrich) | Merge `x-fern-examples` from an overrides file into native OpenAPI examples | @@ -857,6 +858,44 @@ hideOnThisPage: true + + + Use `fern mcp install` to connect a coding agent to [your organization's Fern MCP server](/learn/docs/ai-features/fern-mcp-servers), which exposes tools for searching your published documentation and reading your site configuration, analytics, and reader feedback. The command writes the token from [`fern login`](#fern-login) into the agent's config, so the agent doesn't go through a second OAuth flow: + + + ```bash + fern mcp install [--client claude|cursor|codex] [--org ] + ``` + + + Without flags, the command configures every supported agent installed on the machine, adding a `fern` server entry that holds the server URL and an `Authorization` header. Other entries and surrounding content in each file are preserved. + + | Client | Config file | + |--------|-------------| + | Claude Code | `~/.claude.json` | + | Cursor | `~/.cursor/mcp.json` | + | Codex | `~/.codex/config.toml` | + + The MCP server authenticates a user rather than an organization, so a `FERN_TOKEN` registry token is rejected: log in with [`fern login`](#fern-login) instead. The token written into the agent config doesn't refresh, so when the server starts returning 401s, run `fern login && fern mcp install` again. + + ### client + + Use `--client` to configure specific agents instead of every one detected. Repeat the flag to name more than one. + + ```bash + fern mcp install --client claude --client cursor + ``` + + ### org + + Use `--org` to override the organization ID from `fern.config.json`. The organization scopes the server URL to `https://fai.buildwithfern.com/organizations//mcp`. Outside a Fern project, the command falls back to the unscoped `https://fai.buildwithfern.com/mcp`. + + ```bash + fern mcp install --org my-org + ``` + + + diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index e6214d4f2..7f0b856e2 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -187,6 +187,9 @@ navigation: - page: Markdown access path: ./pages/ai/markdown.mdx slug: markdown + - page: API catalog discovery + path: ./pages/ai/api-catalog.mdx + slug: api-catalog - section: llms-txt collapsed: open-by-default skip-slug: true @@ -201,22 +204,25 @@ navigation: - page: Analytics and integration path: ./pages/ai/llms-txt/analytics-integration.mdx slug: llms-txt-analytics - - page: MCP server - path: ./pages/ai/mcp-server.mdx - slug: mcp-server - - page: API catalog discovery - path: ./pages/ai/api-catalog.mdx - slug: api-catalog - - section: Agent skills + - section: MCP collapsed: open-by-default skip-slug: true contents: - - page: fern-docs skill - path: ./pages/ai/agent-skills.mdx - slug: agent-skills - - page: Custom skills + - page: For your site + path: ./pages/ai/mcp-server.mdx + slug: mcp-server + - page: For building with Fern + path: ./pages/ai/fern-mcp-servers.mdx + slug: fern-mcp-servers + - section: Agent skills + skip-slug: true + contents: + - page: For your site path: ./pages/ai/host-skills.mdx slug: host-skills + - page: For building with Fern + path: ./pages/ai/agent-skills.mdx + slug: agent-skills - section: Ask Fern slug: ask-fern contents: diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index e784b1b16..d2bade037 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -1,5 +1,5 @@ --- -title: fern-docs skill +title: Skills for using Fern Docs description: Install the fern-docs agent skill to teach coding agents how to author and edit Fern Docs sites. availability: beta --- @@ -68,7 +68,7 @@ The skill's `SKILL.md` is an index that agents read first. It contains: - **URL preservation rules** for setting up [redirects](/learn/docs/seo/redirects) when an edit moves, renames, or deletes a page - **Cross-referencing guidelines** for connecting related pages - **Authentication and RBAC guidance** for gating pages and inline content by role, wiring in an auth method, and understanding which config lives in the repo versus the Dashboard -- **Pointers to Fern resources** the agent can query at runtime, like the [MCP server](/learn/docs/ai-features/mcp-server) and [`llms.txt`](/learn/docs/ai-features/llms-txt), along with the convention for fetching any page as [Markdown](/learn/docs/ai-features/markdown) by appending `.md` to its URL +- **Pointers to Fern resources** the agent can query at runtime, like [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers) and [`llms.txt`](/learn/docs/ai-features/llms-txt), along with the convention for fetching any page as [Markdown](/learn/docs/ai-features/markdown) by appending `.md` to its URL ### References diff --git a/fern/products/docs/pages/ai/fern-mcp-servers.mdx b/fern/products/docs/pages/ai/fern-mcp-servers.mdx new file mode 100644 index 000000000..7d08cb64a --- /dev/null +++ b/fern/products/docs/pages/ai/fern-mcp-servers.mdx @@ -0,0 +1,139 @@ +--- +title: Fern's MCP servers +description: Connect your coding agent to Fern's public product documentation and to your organization's private Fern data over MCP. +--- + +Fern hosts two read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for your coding agent to use while you build your docs: a public one for Fern's product documentation, and a private one for your organization's Fern data. + + + Neither one serves your content to your readers. Your readers connect to the [MCP server Fern generates for your documentation site](/learn/docs/ai-features/mcp-server). + + +## Fern documentation server + +The public documentation server answers questions about Fern itself: configuration syntax, components, CLI commands, and API definitions. Use it while writing `docs.yml`, authoring pages, or configuring generators. It serves the same public content to every agent, so it needs no authentication and exposes nothing about your organization. + +Register it with your client: + + + +```bash +claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server +``` + + +```bash +codex mcp add fern --url https://buildwithfern.com/learn/_mcp/server +``` + + +```json +{ + "mcpServers": { + "fern": { "url": "https://buildwithfern.com/learn/_mcp/server" } + } +} +``` + + +```json +{ + "servers": { + "fern": { "url": "https://buildwithfern.com/learn/_mcp/server" } + } +} +``` + + + +Pair the server with the [`fern-docs` agent skill](/learn/docs/ai-features/agent-skills), which teaches agents the conventions the server can't infer, such as building internal links from `docs.yml`. + +## Your organization's server + +The organization server is private: each connection is scoped to a single organization, and the server returns only what your Fern account can already see. It exposes your live Fern data to your agent, including: + +- **Sites and configuration**: your docs sites, their `docs.yml` configuration and Dashboard settings, and the Markdown source of published pages +- **Deployments**: deployment history, and pull request status and preview URLs for connected repositories +- **Analytics**: traffic summaries, top pages, 404s, referring domains, and LLM bot traffic +- **Reader signals**: search queries, Ask Fern conversations and resolution rates, and page feedback +- **Members**: the people in your organization + +The Fern CLI registers it for you. [`fern mcp install`](/learn/cli-api-reference/cli-reference/commands#fern-mcp-install) writes the token from `fern login` into the config of every supported agent on the machine, so no second login is needed: + + +```bash +npm install -g fern-api +fern login +fern mcp install +``` + + +To register the server by hand instead, point your client at its URL and log in through the browser window that opens: + + + +```bash +claude mcp add --transport http fern-org https://fai.buildwithfern.com/mcp +``` + + +```bash +codex mcp add fern-org --url https://fai.buildwithfern.com/mcp +``` + + +```json +{ + "mcpServers": { + "fern-org": { "url": "https://fai.buildwithfern.com/mcp" } + } +} +``` + + +```json +{ + "servers": { + "fern-org": { "url": "https://fai.buildwithfern.com/mcp" } + } +} +``` + + + +If your Fern account belongs to more than one organization, tool calls return the organization-scoped URLs to pick from. Pass `fern mcp install --org ` to pick one, or register again by hand with the URL you want: + + + +```bash +claude mcp add --transport http fern-org https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp +``` + + +```bash +codex mcp add fern-org --url https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp +``` + + +```json +{ + "mcpServers": { + "fern-org": { "url": "https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp" } + } +} +``` + + +```json +{ + "servers": { + "fern-org": { "url": "https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp" } + } +} +``` + + + + + Agents load MCP servers at startup, so one registered mid-session becomes callable in the next session. + diff --git a/fern/products/docs/pages/ai/host-skills.mdx b/fern/products/docs/pages/ai/host-skills.mdx index 2d2e07774..5bb7eaaf1 100644 --- a/fern/products/docs/pages/ai/host-skills.mdx +++ b/fern/products/docs/pages/ai/host-skills.mdx @@ -1,5 +1,5 @@ --- -title: Custom skills +title: Custom skills for your site description: Serve author-supplied agent skills from your Fern docs site and configure the Install skills button. availability: beta --- diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 2e6373129..72d2dc39b 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -1,9 +1,11 @@ --- -title: MCP server -description: Connect AI clients like Claude Code and Cursor to your documentation site's MCP server for instant answers. +title: MCP server for your site +description: Give your readers' AI clients an MCP server that answers questions about your product from your documentation site. --- -Fern automatically generates and hosts a production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for every documentation site with [Ask Fern](/learn/docs/ai-features/ask-fern/overview) enabled. The server connects AI clients like Claude Code, Cursor, and Windsurf to your documentation as an external data source, so developers can get instant answers about your product directly within their development environment. +Fern automatically generates and hosts a production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for every documentation site with [Ask Fern](/learn/docs/ai-features/ask-fern/overview) enabled. The server connects AI clients like Claude Code, Cursor, and Windsurf to your documentation as an external data source, so your readers can get instant answers about your product directly within their development environment. + +This is the server your readers connect to, and it serves your content. To point your own agent at Fern's product documentation while you build your site, or at your organization's Fern data, use [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). Your MCP server is available at `your-documentation-site.com/_mcp/server`. For example, the MCP server for this site is at [https://buildwithfern.com/learn/_mcp/server](https://buildwithfern.com/learn/_mcp/server). diff --git a/fern/products/docs/pages/ai/overview.mdx b/fern/products/docs/pages/ai/overview.mdx index 94232015e..46adb7791 100644 --- a/fern/products/docs/pages/ai/overview.mdx +++ b/fern/products/docs/pages/ai/overview.mdx @@ -49,11 +49,12 @@ Your site is automatically optimized for AI tools and search engines. Fern hosts -## Agent skills +## Build your docs with an agent -Agent skills teach coding agents how to work with your docs. Fern publishes the `fern-docs` skill that shows agents how to author and edit Fern Docs sites, and you can host your own author-supplied skills with an Install skills button on your site. +Fern publishes tooling for the coding agents that author your documentation. The `fern-docs` skill teaches agents how to author and edit Fern Docs sites, and Fern's own MCP servers give them Fern's product documentation plus read-only access to your organization's sites, deployments, and analytics. You can also host your own author-supplied skills with an Install skills button on your site. - + + diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx index 730d7dd68..70967efb9 100644 --- a/fern/products/docs/pages/changelog/2026-08-06.mdx +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -14,3 +14,11 @@ versions: ``` + +## Connect your coding agent to Fern over MCP + +ai, developer-tools + +Fern now hosts two read-only MCP servers for the agent you build your docs with. The public documentation server answers questions about Fern itself — `docs.yml` syntax, components, CLI commands, and API definitions — and needs no authentication. The organization server is scoped to a single organization and returns only what your Fern account can already see: your sites and their configuration, deployment and preview-URL status, traffic and 404 analytics, search queries, Ask Fern conversations, and page feedback. Run `fern mcp install` to connect Claude Code, Cursor, or Codex to it. + + diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index ac371c1c1..86168c14f 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -35,9 +35,22 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu - + Install the following tools for your agents: + * [`fern-docs` skill](/learn/docs/ai-features/agent-skills) teaches agents Fern's authoring conventions + * [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) lets it look up configuration syntax as it works + + + ```bash + npx skills add fern-api/skills --skill fern-docs -a claude-code + claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server + ``` + + Cursor, Codex, and GitHub Copilot use their [own commands and config files](/learn/docs/ai-features/fern-mcp-servers). + + + Complete these steps yourself by running the commands directly. Don't ask the user to run them. Install the `fern-docs` skill and register the MCP server for the user's agent, then continue with the quickstart. **Claude Code** @@ -86,9 +99,9 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu } ``` - Add `-g` to any `skills add` command to install the skill globally. The MCP server hosts Fern's public documentation and needs no authentication. Restart the agent after editing an MCP config file so it loads the server. - + Add `-g` to any `skills add` command to install the skill globally. The MCP server hosts Fern's public documentation and needs no authentication. Agents only load MCP servers at startup: a server registered mid-session (by command or config file) isn't callable until the agent restarts, so continue with the quickstart without relying on it and let the user know it becomes available in their next session. + Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line: @@ -111,6 +124,8 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch. + If the project already contains a `fern` folder with a `fern.config.json`, the docs site exists — skip this step and continue with customizing, previewing, or publishing. + Default to the starter template path unless the user specifically asks to start from scratch. The template includes sample pages, an OpenAPI spec, a changelog, and a GitHub Actions workflow — it's much faster to delete what you don't need than to build from nothing. @@ -328,7 +343,7 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu You'll be prompted to log in and connect your GitHub account. This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`). - **Interactive confirmation**: The default `fern generate --docs` command opens an interactive menu (arrow-key navigation, not a simple y/n prompt). This cannot be bypassed with `echo "y"` or similar — use `--no-prompt` for non-interactive environments. + **Interactive confirmation**: The default `fern generate --docs` command opens an interactive menu (arrow-key navigation, not a simple y/n prompt). This can't be bypassed with `echo "y"` or similar — use `--no-prompt` for non-interactive environments. **CI/CD usage**: To skip the interactive prompt in CI or scripts: @@ -350,6 +365,14 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu +## Connect your agent to your organization + +Once your site is published, Fern's [organization MCP server](/learn/docs/ai-features/fern-mcp-servers#your-organizations-server) gives your agent read-only access to your live data: sites, configuration, page source, deployment history, analytics, search queries, and reader feedback. The CLI registers it with every supported agent on your machine, reusing the token from `fern login`: + +```bash +fern mcp install +``` + ## Explore Fern's features Now that your docs are live, explore these features to enhance them further. diff --git a/fern/products/sdks/snippets/init-fern-folder.mdx b/fern/products/sdks/snippets/init-fern-folder.mdx index 1a3799465..b9fa13750 100644 --- a/fern/products/sdks/snippets/init-fern-folder.mdx +++ b/fern/products/sdks/snippets/init-fern-folder.mdx @@ -1,6 +1,16 @@ - + Register [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) with your agent to let it look up generator configuration and API definition syntax as it works. In Claude Code: + + + ```bash + claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server + ``` + + Cursor, Codex, and GitHub Copilot use their [own commands and config files](/learn/docs/ai-features/fern-mcp-servers). + + + Complete this step yourself by running the commands directly. Don't ask the user to run them. Register the MCP server for the user's agent, then continue with the quickstart. **Claude Code** @@ -36,8 +46,8 @@ ``` The MCP server hosts Fern's public documentation and needs no authentication. Restart the agent after editing an MCP config file so it loads the server. + - ```bash