From 4c33439f49f074114656dddc9a7d98f96ef1cc3b Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 16:57:59 +0000 Subject: [PATCH 01/11] docs: add authenticated Fern MCP server to Docs quickstart Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../docs/pages/getting-started/quickstart.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index 26f1366ad..3c208394e 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -328,7 +328,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 +350,16 @@ 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, connect the authenticated Fern MCP server so your coding agent can read your live organization data: docs sites, configuration, source files, deployment history, analytics, search queries, and reader feedback. The server is read-only and authenticates with your Fern account through OAuth. + +```bash +claude mcp add --transport http fern-org https://fai.buildwithfern.com/mcp +``` + +For other clients, add `https://fai.buildwithfern.com/mcp` to your MCP configuration. Your client opens a browser window to log in the first time it connects. This server is separate from the public documentation server at `https://buildwithfern.com/learn/_mcp/server`, which serves Fern's product documentation and needs no authentication. + ## Explore Fern's features Now that your docs are live, explore these features to enhance them further. From 7c5144a6b4f6139fcdb17c39c5035c3ae964ac47 Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 17:00:07 +0000 Subject: [PATCH 02/11] docs: harden quickstart agent guidance for existing repos and MCP load timing Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/getting-started/quickstart.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index 3c208394e..c4ac75343 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -86,7 +86,7 @@ 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. @@ -111,6 +111,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. @@ -358,7 +360,7 @@ Once your site is published, connect the authenticated Fern MCP server so your c claude mcp add --transport http fern-org https://fai.buildwithfern.com/mcp ``` -For other clients, add `https://fai.buildwithfern.com/mcp` to your MCP configuration. Your client opens a browser window to log in the first time it connects. This server is separate from the public documentation server at `https://buildwithfern.com/learn/_mcp/server`, which serves Fern's product documentation and needs no authentication. +For other clients, add `https://fai.buildwithfern.com/mcp` to your MCP configuration. Your client opens a browser window to log in the first time it connects — like `fern login`, this step needs a human at the browser and can't be completed by a coding agent alone. This server is separate from the public documentation server at `https://buildwithfern.com/learn/_mcp/server`, which serves Fern's product documentation and needs no authentication. ## Explore Fern's features From 8c9ccb2a182474fca36ae5182cec5995fa19d089 Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 17:22:31 +0000 Subject: [PATCH 03/11] docs: add standalone Fern MCP servers page and surface agent setup to humans Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .vale/styles/Microsoft/BiasFree.yml | 14 +++ .vale/styles/Microsoft/ExclamationPoints.yml | 7 ++ .vale/styles/Microsoft/Jargon.yml | 11 ++ .vale/styles/Microsoft/Militaristic.yml | 24 +++++ .vale/styles/Microsoft/QuestionMarks.yml | 7 ++ .vale/styles/Microsoft/UIVerbs.yml | 9 ++ .vale/styles/Microsoft/Uppercase.yml | 11 ++ fern/products/docs/docs.yml | 3 + fern/products/docs/pages/ai/agent-skills.mdx | 2 +- .../docs/pages/ai/fern-mcp-servers.mdx | 102 ++++++++++++++++++ fern/products/docs/pages/ai/mcp-server.mdx | 2 + fern/products/docs/pages/ai/overview.mdx | 7 +- .../docs/pages/getting-started/quickstart.mdx | 19 +++- .../sdks/snippets/init-fern-folder.mdx | 14 ++- 14 files changed, 221 insertions(+), 11 deletions(-) create mode 100644 .vale/styles/Microsoft/BiasFree.yml create mode 100644 .vale/styles/Microsoft/ExclamationPoints.yml create mode 100644 .vale/styles/Microsoft/Jargon.yml create mode 100644 .vale/styles/Microsoft/Militaristic.yml create mode 100644 .vale/styles/Microsoft/QuestionMarks.yml create mode 100644 .vale/styles/Microsoft/UIVerbs.yml create mode 100644 .vale/styles/Microsoft/Uppercase.yml create mode 100644 fern/products/docs/pages/ai/fern-mcp-servers.mdx diff --git a/.vale/styles/Microsoft/BiasFree.yml b/.vale/styles/Microsoft/BiasFree.yml new file mode 100644 index 000000000..261e39b3d --- /dev/null +++ b/.vale/styles/Microsoft/BiasFree.yml @@ -0,0 +1,14 @@ +extends: substitution +message: "Consider '%s' instead of '%s'." +link: https://learn.microsoft.com/en-us/style-guide/bias-free-communication +level: warning +ignorecase: true +action: + name: replace +# Culturally sensitive terms; see GenderBias.yml for gendered terms. +swap: + '(?:demilitarized zone|DMZ)': perimeter network + 'master/slave': master/subordinate + 'sanity check': quick check + 'spirit animal': role model + hangs: stops responding diff --git a/.vale/styles/Microsoft/ExclamationPoints.yml b/.vale/styles/Microsoft/ExclamationPoints.yml new file mode 100644 index 000000000..774fedf82 --- /dev/null +++ b/.vale/styles/Microsoft/ExclamationPoints.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use exclamation points sparingly." +link: https://learn.microsoft.com/en-us/style-guide/punctuation/exclamation-points +level: suggestion +nonword: true +tokens: + - '\w!(?:\s|$)' diff --git a/.vale/styles/Microsoft/Jargon.yml b/.vale/styles/Microsoft/Jargon.yml new file mode 100644 index 000000000..999d43667 --- /dev/null +++ b/.vale/styles/Microsoft/Jargon.yml @@ -0,0 +1,11 @@ +extends: substitution +message: "Consider using '%s' instead of the jargon '%s'." +link: https://learn.microsoft.com/en-us/style-guide/word-choice/avoid-jargon +level: suggestion +ignorecase: true +action: + name: replace +swap: + bucketize: group + glyph: symbol + leverage: take advantage of diff --git a/.vale/styles/Microsoft/Militaristic.yml b/.vale/styles/Microsoft/Militaristic.yml new file mode 100644 index 000000000..45c0f027d --- /dev/null +++ b/.vale/styles/Microsoft/Militaristic.yml @@ -0,0 +1,24 @@ +extends: substitution +message: "Consider '%s' instead of '%s'." +link: https://learn.microsoft.com/en-us/style-guide/militaristic-language +level: suggestion +ignorecase: true +action: + name: replace +# The guide scopes its table to cybersecurity writing, so the generic verbs it +# also lists (combat, fight, guard, ward) are omitted here: without that context +# they'd fire on ordinary prose. +swap: + '(?:cyber ?)?kill chain': cyberattack chain + 'defense-in-depth approach': multilayered approach + 'external attack surface': external exposure + 'first line of defense': protection + 'frontline analysts': security analysts + 'locked down': secured + adversaries: threat actors + adversary: threat actor + attackers: cyberattackers + attacker: cyberattacker + blast radius: impact + fortifications: protection + frontlines: defense diff --git a/.vale/styles/Microsoft/QuestionMarks.yml b/.vale/styles/Microsoft/QuestionMarks.yml new file mode 100644 index 000000000..2034033c0 --- /dev/null +++ b/.vale/styles/Microsoft/QuestionMarks.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use questions sparingly." +link: https://learn.microsoft.com/en-us/style-guide/punctuation/question-marks +level: suggestion +nonword: true +tokens: + - '\w\?(?:\s|$)' diff --git a/.vale/styles/Microsoft/UIVerbs.yml b/.vale/styles/Microsoft/UIVerbs.yml new file mode 100644 index 000000000..ed6ef85a1 --- /dev/null +++ b/.vale/styles/Microsoft/UIVerbs.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'select' instead of the input-specific verb '%s'." +link: https://learn.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui +level: warning +ignorecase: true +# 'right-click' and 'double-click' are explicitly allowed by the guide. +tokens: + - '(? + +```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 exposes your live Fern data to your agent, scoped to one organization per connection: + +- **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 server is read-only. Tools that edit docs are available to the [Fern agent in the Dashboard](https://dashboard.buildwithfern.com), not over MCP. + + + +```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" } + } +} +``` + + + +Your client opens a browser window for you to log in the first time it connects. Like `fern login`, this step needs a human at the browser and can't be completed by a coding agent on its own. + +If your Fern account belongs to more than one organization, the server can't pick one for you: tool calls return the organization-scoped URLs to choose from. Reconnect using the URL of the organization you want. + +```bash +claude mcp add --transport http fern-org \ + https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp +``` + +Agents load MCP servers at startup, so a server registered mid-session, by command or by editing a config file, becomes callable in the next session. diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 0892ec6d8..e446e333b 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -5,6 +5,8 @@ description: Connect AI clients like Claude Code and Cursor to your documentatio 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. +This server answers questions about *your* product. To point an agent at Fern's product documentation or at your organization's Fern data instead, 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). ## Connect to your 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/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index c4ac75343..949440b23 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -35,9 +35,20 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu - + Working with a coding agent is optional, but it speeds up the rest of this guide. Two pieces of setup give the agent what it needs: the [`fern-docs` skill](/learn/docs/ai-features/agent-skills) teaches it Fern's authoring conventions, and [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) lets it look up configuration syntax as it works. In Claude Code: + + + ```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, listed in [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). An agent that reads this guide runs this step for itself before continuing. + + + 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** @@ -87,8 +98,8 @@ 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. 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: @@ -354,14 +365,12 @@ 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, connect the authenticated Fern MCP server so your coding agent can read your live organization data: docs sites, configuration, source files, deployment history, analytics, search queries, and reader feedback. The server is read-only and authenticates with your Fern account through OAuth. +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. It authenticates with your Fern account through OAuth, so the first connection opens a browser window for you to log in. ```bash claude mcp add --transport http fern-org https://fai.buildwithfern.com/mcp ``` -For other clients, add `https://fai.buildwithfern.com/mcp` to your MCP configuration. Your client opens a browser window to log in the first time it connects — like `fern login`, this step needs a human at the browser and can't be completed by a coding agent alone. This server is separate from the public documentation server at `https://buildwithfern.com/learn/_mcp/server`, which serves Fern's product documentation and needs no authentication. - ## 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..f964e8b24 100644 --- a/fern/products/sdks/snippets/init-fern-folder.mdx +++ b/fern/products/sdks/snippets/init-fern-folder.mdx @@ -1,6 +1,16 @@ - + Working with a coding agent is optional. Registering [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) lets 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, listed in [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). An agent that reads this guide runs this step for itself before continuing. + + + 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 From 3e0ef80ade3e73de959ae43a8291aaa759f18865 Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 17:22:53 +0000 Subject: [PATCH 04/11] chore: drop vendored Vale style files added by local sync Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .vale/styles/Microsoft/BiasFree.yml | 14 ------------ .vale/styles/Microsoft/ExclamationPoints.yml | 7 ------ .vale/styles/Microsoft/Jargon.yml | 11 --------- .vale/styles/Microsoft/Militaristic.yml | 24 -------------------- .vale/styles/Microsoft/QuestionMarks.yml | 7 ------ .vale/styles/Microsoft/UIVerbs.yml | 9 -------- .vale/styles/Microsoft/Uppercase.yml | 11 --------- 7 files changed, 83 deletions(-) delete mode 100644 .vale/styles/Microsoft/BiasFree.yml delete mode 100644 .vale/styles/Microsoft/ExclamationPoints.yml delete mode 100644 .vale/styles/Microsoft/Jargon.yml delete mode 100644 .vale/styles/Microsoft/Militaristic.yml delete mode 100644 .vale/styles/Microsoft/QuestionMarks.yml delete mode 100644 .vale/styles/Microsoft/UIVerbs.yml delete mode 100644 .vale/styles/Microsoft/Uppercase.yml diff --git a/.vale/styles/Microsoft/BiasFree.yml b/.vale/styles/Microsoft/BiasFree.yml deleted file mode 100644 index 261e39b3d..000000000 --- a/.vale/styles/Microsoft/BiasFree.yml +++ /dev/null @@ -1,14 +0,0 @@ -extends: substitution -message: "Consider '%s' instead of '%s'." -link: https://learn.microsoft.com/en-us/style-guide/bias-free-communication -level: warning -ignorecase: true -action: - name: replace -# Culturally sensitive terms; see GenderBias.yml for gendered terms. -swap: - '(?:demilitarized zone|DMZ)': perimeter network - 'master/slave': master/subordinate - 'sanity check': quick check - 'spirit animal': role model - hangs: stops responding diff --git a/.vale/styles/Microsoft/ExclamationPoints.yml b/.vale/styles/Microsoft/ExclamationPoints.yml deleted file mode 100644 index 774fedf82..000000000 --- a/.vale/styles/Microsoft/ExclamationPoints.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Use exclamation points sparingly." -link: https://learn.microsoft.com/en-us/style-guide/punctuation/exclamation-points -level: suggestion -nonword: true -tokens: - - '\w!(?:\s|$)' diff --git a/.vale/styles/Microsoft/Jargon.yml b/.vale/styles/Microsoft/Jargon.yml deleted file mode 100644 index 999d43667..000000000 --- a/.vale/styles/Microsoft/Jargon.yml +++ /dev/null @@ -1,11 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of the jargon '%s'." -link: https://learn.microsoft.com/en-us/style-guide/word-choice/avoid-jargon -level: suggestion -ignorecase: true -action: - name: replace -swap: - bucketize: group - glyph: symbol - leverage: take advantage of diff --git a/.vale/styles/Microsoft/Militaristic.yml b/.vale/styles/Microsoft/Militaristic.yml deleted file mode 100644 index 45c0f027d..000000000 --- a/.vale/styles/Microsoft/Militaristic.yml +++ /dev/null @@ -1,24 +0,0 @@ -extends: substitution -message: "Consider '%s' instead of '%s'." -link: https://learn.microsoft.com/en-us/style-guide/militaristic-language -level: suggestion -ignorecase: true -action: - name: replace -# The guide scopes its table to cybersecurity writing, so the generic verbs it -# also lists (combat, fight, guard, ward) are omitted here: without that context -# they'd fire on ordinary prose. -swap: - '(?:cyber ?)?kill chain': cyberattack chain - 'defense-in-depth approach': multilayered approach - 'external attack surface': external exposure - 'first line of defense': protection - 'frontline analysts': security analysts - 'locked down': secured - adversaries: threat actors - adversary: threat actor - attackers: cyberattackers - attacker: cyberattacker - blast radius: impact - fortifications: protection - frontlines: defense diff --git a/.vale/styles/Microsoft/QuestionMarks.yml b/.vale/styles/Microsoft/QuestionMarks.yml deleted file mode 100644 index 2034033c0..000000000 --- a/.vale/styles/Microsoft/QuestionMarks.yml +++ /dev/null @@ -1,7 +0,0 @@ -extends: existence -message: "Use questions sparingly." -link: https://learn.microsoft.com/en-us/style-guide/punctuation/question-marks -level: suggestion -nonword: true -tokens: - - '\w\?(?:\s|$)' diff --git a/.vale/styles/Microsoft/UIVerbs.yml b/.vale/styles/Microsoft/UIVerbs.yml deleted file mode 100644 index ed6ef85a1..000000000 --- a/.vale/styles/Microsoft/UIVerbs.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: "Use 'select' instead of the input-specific verb '%s'." -link: https://learn.microsoft.com/en-us/style-guide/procedures-instructions/describing-interactions-with-ui -level: warning -ignorecase: true -# 'right-click' and 'double-click' are explicitly allowed by the guide. -tokens: - - '(? Date: Thu, 6 Aug 2026 13:51:58 -0400 Subject: [PATCH 05/11] cut down quickstart language --- fern/products/docs/pages/getting-started/quickstart.mdx | 6 ++++-- fern/products/sdks/snippets/init-fern-folder.mdx | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index 949440b23..0188f1dfe 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -37,7 +37,9 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu - Working with a coding agent is optional, but it speeds up the rest of this guide. Two pieces of setup give the agent what it needs: the [`fern-docs` skill](/learn/docs/ai-features/agent-skills) teaches it Fern's authoring conventions, and [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) lets it look up configuration syntax as it works. In Claude Code: + 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 @@ -45,7 +47,7 @@ Build and publish a docs site with Fern. Follow the [Docs quickstart](https://bu claude mcp add --transport http fern https://buildwithfern.com/learn/_mcp/server ``` - Cursor, Codex, and GitHub Copilot use their own commands and config files, listed in [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). An agent that reads this guide runs this step for itself before continuing. + Cursor, Codex, and GitHub Copilot use their [own commands and config files](/learn/docs/ai-features/fern-mcp-servers). diff --git a/fern/products/sdks/snippets/init-fern-folder.mdx b/fern/products/sdks/snippets/init-fern-folder.mdx index f964e8b24..b9fa13750 100644 --- a/fern/products/sdks/snippets/init-fern-folder.mdx +++ b/fern/products/sdks/snippets/init-fern-folder.mdx @@ -1,13 +1,13 @@ - Working with a coding agent is optional. Registering [Fern's documentation MCP server](/learn/docs/ai-features/fern-mcp-servers) lets it look up generator configuration and API definition syntax as it works. In Claude Code: + 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, listed in [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). An agent that reads this guide runs this step for itself before continuing. + Cursor, Codex, and GitHub Copilot use their [own commands and config files](/learn/docs/ai-features/fern-mcp-servers). From e87e512bf2d7d03621c4e7311c7fe37b7b410242 Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 17:58:22 +0000 Subject: [PATCH 06/11] docs: use plain placeholder in org-scoped MCP URL Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/docs/pages/ai/fern-mcp-servers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/ai/fern-mcp-servers.mdx b/fern/products/docs/pages/ai/fern-mcp-servers.mdx index 1608d6820..8d6d0ba77 100644 --- a/fern/products/docs/pages/ai/fern-mcp-servers.mdx +++ b/fern/products/docs/pages/ai/fern-mcp-servers.mdx @@ -96,7 +96,7 @@ If your Fern account belongs to more than one organization, the server can't pic ```bash claude mcp add --transport http fern-org \ - https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp + https://fai.buildwithfern.com/organizations/your-organization/mcp ``` Agents load MCP servers at startup, so a server registered mid-session, by command or by editing a config file, becomes callable in the next session. From 2e7fa1bae4d7329559003a7d4631fd24aeb59972 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 6 Aug 2026 14:17:39 -0400 Subject: [PATCH 07/11] clarify content --- fern/products/docs/docs.yml | 31 +++++----- fern/products/docs/pages/ai/agent-skills.mdx | 2 +- .../docs/pages/ai/fern-mcp-servers.mdx | 61 +++++++++++++------ fern/products/docs/pages/ai/host-skills.mdx | 2 +- fern/products/docs/pages/ai/mcp-server.mdx | 8 +-- 5 files changed, 67 insertions(+), 37 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index f89bcd275..f1cb1b1b7 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,25 +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: Fern's MCP servers - path: ./pages/ai/fern-mcp-servers.mdx - slug: fern-mcp-servers - - 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 7f47be96e..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 --- diff --git a/fern/products/docs/pages/ai/fern-mcp-servers.mdx b/fern/products/docs/pages/ai/fern-mcp-servers.mdx index 1608d6820..8b050deb5 100644 --- a/fern/products/docs/pages/ai/fern-mcp-servers.mdx +++ b/fern/products/docs/pages/ai/fern-mcp-servers.mdx @@ -1,18 +1,19 @@ --- title: Fern's MCP servers -description: Connect your coding agent to Fern's product documentation and to your organization's docs data over MCP. +description: Connect your coding agent to Fern's public product documentation and to your organization's private Fern data over MCP. --- -Fern hosts two [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for teams that build with Fern. One serves Fern's product documentation to any agent; the other serves your organization's own data after you log in. Both are read-only, and both are separate from the [MCP server Fern generates for your documentation site](/learn/docs/ai-features/mcp-server), which answers your readers' questions about your product. +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. -| Server | URL | Authentication | -| --- | --- | --- | -| Fern documentation | `https://buildwithfern.com/learn/_mcp/server` | None | -| Your Fern organization | `https://fai.buildwithfern.com/mcp` | OAuth with your Fern account | + + 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 +## Public: Fern documentation server -The 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 needs no authentication. +The 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: @@ -47,9 +48,9 @@ codex mcp add 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 +## Private: your organization's server -The organization server exposes your live Fern data to your agent, scoped to one organization per connection: +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 @@ -57,7 +58,7 @@ The organization server exposes your live Fern data to your agent, scoped to one - **Reader signals**: search queries, Ask Fern conversations and resolution rates, and page feedback - **Members**: the people in your organization -The server is read-only. Tools that edit docs are available to the [Fern agent in the Dashboard](https://dashboard.buildwithfern.com), not over MCP. +Register it with your client (opens a browser window for you to log in): @@ -90,13 +91,39 @@ codex mcp add fern-org --url https://fai.buildwithfern.com/mcp -Your client opens a browser window for you to log in the first time it connects. Like `fern login`, this step needs a human at the browser and can't be completed by a coding agent on its own. - -If your Fern account belongs to more than one organization, the server can't pick one for you: tool calls return the organization-scoped URLs to choose from. Reconnect using the URL of the organization you want. +If your Fern account belongs to more than one organization, tool calls return the organization-scoped URLs to pick from. Register again with the one you want: + + ```bash -claude mcp add --transport http fern-org \ - https://fai.buildwithfern.com/organizations/{{YOUR_ORGANIZATION}}/mcp +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 a server registered mid-session, by command or by editing a config file, becomes callable in the next session. + + 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 e446e333b..22965b51e 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -1,11 +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 server answers questions about *your* product. To point an agent at Fern's product documentation or at your organization's Fern data instead, use [Fern's MCP servers](/learn/docs/ai-features/fern-mcp-servers). +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). From ae20033e3927b1886a9595f943d858c1bccdbdf5 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 6 Aug 2026 14:21:38 -0400 Subject: [PATCH 08/11] add changelog --- fern/products/docs/pages/changelog/2026-08-06.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 fern/products/docs/pages/changelog/2026-08-06.mdx diff --git a/fern/products/docs/pages/changelog/2026-08-06.mdx b/fern/products/docs/pages/changelog/2026-08-06.mdx new file mode 100644 index 000000000..680650ede --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-08-06.mdx @@ -0,0 +1,8 @@ +## 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. + + + From f54ce6150e27f07830cf7840d7068fff2c843425 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 8 Aug 2026 17:08:10 +0000 Subject: [PATCH 09/11] docs: document `fern mcp install` Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../cli-api-reference/pages/commands.mdx | 39 +++++++++++++++++++ fern/products/docs/pages/ai/mcp-server.mdx | 2 + 2 files changed, 41 insertions(+) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index be13bd1b3..8cac55458 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 Fern's MCP server, 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` | + + A [`fern token`](#fern-token) API key is rejected, because the MCP server authenticates a user rather than an organization. The token written into the agent config doesn't refresh: 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 from [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson). 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`, which resolves the organization from your login and fails if that login covers several. + + ```bash + fern mcp install --org my-org + ``` + + + diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index 72d2dc39b..ad645453e 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -104,3 +104,5 @@ This is especially useful on [authenticated sites](/learn/docs/authentication/ov Agents can also fetch documentation directly over HTTP. Fern serves clean Markdown via [per-page URLs and `llms.txt`](/learn/docs/ai-features/markdown) — including on authenticated sites. +Fern hosts a separate MCP server for your Fern organization, which searches your published pages and reads your site configuration, analytics, and reader feedback. Run [`fern mcp install`](/learn/cli-api-reference/cli-reference/commands#fern-mcp-install) to connect Claude Code, Cursor, or Codex to it. + From 811db72cbaa7faa44749d9a1b7914d29f29b9ae1 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sat, 8 Aug 2026 17:09:19 +0000 Subject: [PATCH 10/11] docs: tighten fern mcp install section Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/cli-api-reference/pages/commands.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 8cac55458..267d62c49 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -868,6 +868,16 @@ hideOnThisPage: true ``` + From a machine with no Fern CLI yet: + + + ```bash + npm i -g fern-api + fern login + fern mcp install + ``` + + 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 | @@ -876,7 +886,7 @@ hideOnThisPage: true | Cursor | `~/.cursor/mcp.json` | | Codex | `~/.codex/config.toml` | - A [`fern token`](#fern-token) API key is rejected, because the MCP server authenticates a user rather than an organization. The token written into the agent config doesn't refresh: when the server starts returning 401s, run `fern login && fern mcp install` again. + 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 @@ -888,7 +898,7 @@ hideOnThisPage: true ### org - Use `--org` to override the organization from [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson). 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`, which resolves the organization from your login and fails if that login covers several. + 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 From f64fe8dc6def7d21df2121179a89d54a1d122038 Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Tue, 11 Aug 2026 18:23:28 +0000 Subject: [PATCH 11/11] docs: make fern mcp install the setup path for the org MCP server Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../cli-api-reference/pages/commands.mdx | 12 +---------- .../docs/pages/ai/fern-mcp-servers.mdx | 20 ++++++++++++++----- fern/products/docs/pages/ai/mcp-server.mdx | 2 -- .../docs/pages/getting-started/quickstart.mdx | 4 ++-- 4 files changed, 18 insertions(+), 20 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 267d62c49..5b227f7df 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -860,7 +860,7 @@ hideOnThisPage: true - Use `fern mcp install` to connect a coding agent to Fern's MCP server, 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: + 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 @@ -868,16 +868,6 @@ hideOnThisPage: true ``` - From a machine with no Fern CLI yet: - - - ```bash - npm i -g fern-api - fern login - fern mcp install - ``` - - 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 | diff --git a/fern/products/docs/pages/ai/fern-mcp-servers.mdx b/fern/products/docs/pages/ai/fern-mcp-servers.mdx index 8b050deb5..7d08cb64a 100644 --- a/fern/products/docs/pages/ai/fern-mcp-servers.mdx +++ b/fern/products/docs/pages/ai/fern-mcp-servers.mdx @@ -9,9 +9,9 @@ Fern hosts two read-only [Model Context Protocol (MCP)](https://modelcontextprot 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). -## Public: Fern documentation server +## Fern documentation server -The 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. +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: @@ -48,7 +48,7 @@ codex mcp add 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`. -## Private: your organization's server +## 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: @@ -58,7 +58,17 @@ The organization server is private: each connection is scoped to a single organi - **Reader signals**: search queries, Ask Fern conversations and resolution rates, and page feedback - **Members**: the people in your organization -Register it with your client (opens a browser window for you to log in): +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: @@ -91,7 +101,7 @@ codex mcp add 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. Register again with the one you want: +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: diff --git a/fern/products/docs/pages/ai/mcp-server.mdx b/fern/products/docs/pages/ai/mcp-server.mdx index ad645453e..72d2dc39b 100644 --- a/fern/products/docs/pages/ai/mcp-server.mdx +++ b/fern/products/docs/pages/ai/mcp-server.mdx @@ -104,5 +104,3 @@ This is especially useful on [authenticated sites](/learn/docs/authentication/ov Agents can also fetch documentation directly over HTTP. Fern serves clean Markdown via [per-page URLs and `llms.txt`](/learn/docs/ai-features/markdown) — including on authenticated sites. -Fern hosts a separate MCP server for your Fern organization, which searches your published pages and reads your site configuration, analytics, and reader feedback. Run [`fern mcp install`](/learn/cli-api-reference/cli-reference/commands#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 4de8cd1fb..86168c14f 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -367,10 +367,10 @@ 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. It authenticates with your Fern account through OAuth, so the first connection opens a browser window for you to log in. +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 -claude mcp add --transport http fern-org https://fai.buildwithfern.com/mcp +fern mcp install ``` ## Explore Fern's features