From 4c33439f49f074114656dddc9a7d98f96ef1cc3b Mon Sep 17 00:00:00 2001 From: "mathieu.legault" Date: Thu, 6 Aug 2026 16:57:59 +0000 Subject: [PATCH 1/8] 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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 6/8] 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 7/8] 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 8/8] 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. + + +