---
title: "MCP Server"
description: "Expose your docs as MCP tools and resources over stdio, /mcp, or /.well-known/mcp"
canonical_url: "https://docs.farming-labs.dev/docs/customization/mcp"
markdown_url: "https://docs.farming-labs.dev/docs/customization/mcp.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1300
  task: "Expose the docs MCP server over stdio or Streamable HTTP with optional explicit authentication."
  outcome: "An MCP client initializes successfully and can discover, search, and read the configured documentation resources."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The docs API and framework public forwarder are already wired."
    - "Choose stdio for local use or Streamable HTTP for a shared endpoint."
    - "Keep HTTP public by default and add security.authenticate only when the deployment requires access control."
    - "For OAuth discovery, have an authorization-server issuer URL and decide which scopes are advertised and required."
  files:
    - "docs.config.ts"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "app/api/docs/route.ts"
    - "src/routes/$.ts"
    - "src/hooks.server.ts"
    - "src/middleware.ts"
    - "server/middleware/docs-public.ts"
    - ".cursor/mcp.json"
    - ".vscode/mcp.json"
  commands:
    - run: "pnpm exec docs doctor --agent"
      description: "Confirm MCP routes and discovery metadata agree with docs.config."
  sideEffects:
    - "A public HTTP MCP endpoint exposes the same documentation content as other public agent surfaces."
    - "An authentication callback can reject clients and may depend on an external identity system."
    - "OAuth protected-resource metadata remains public so clients can discover how to authenticate."
  verification:
    - run: "pnpm exec docs doctor --agent"
      expect: "MCP access and discovery/config/schema consistency pass."
    - description: "Initialize an MCP client and call list_docs followed by read_page for a known route."
      expect: "The initialize request succeeds and both tools return structured content for the configured docs corpus."
  rollback:
    - "Set mcp.enabled to false, remove client configuration, and restore custom route or authentication wiring."
  failureModes:
    - symptom: "The client receives 404 from /mcp or /.well-known/mcp."
      resolution: "Align mcp.route with the framework public forwarder and keep the documented aliases pointing at the canonical handler."
    - symptom: "Every HTTP request receives 401 after authentication is enabled."
      resolution: "Return a principal from security.authenticate for valid credentials and test the callback independently of MCP tools."
    - symptom: "Protected-resource metadata returns 404."
      resolution: "Configure both security.authenticate and a non-empty protectedResource.authorizationServers list, then verify the public forwarder includes the metadata route."
    - symptom: "An authenticated client receives 403 insufficient_scope."
      resolution: "Return all protectedResource.requiredScopes in the principal scopes, or narrow the endpoint-wide requirements."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Expose the docs MCP server over stdio or Streamable HTTP with optional explicit authentication.
Outcome: An MCP client initializes successfully and can discover, search, and read the configured documentation resources.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The docs API and framework public forwarder are already wired.
- Choose stdio for local use or Streamable HTTP for a shared endpoint.
- Keep HTTP public by default and add security.authenticate only when the deployment requires access control.
- For OAuth discovery, have an authorization-server issuer URL and decide which scopes are advertised and required.

### Files

- `docs.config.ts`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `app/api/docs/route.ts`
- `src/routes/$.ts`
- `src/hooks.server.ts`
- `src/middleware.ts`
- `server/middleware/docs-public.ts`
- `.cursor/mcp.json`
- `.vscode/mcp.json`

### Commands

- `pnpm exec docs doctor --agent` — Confirm MCP routes and discovery metadata agree with docs.config.

### Side Effects

- A public HTTP MCP endpoint exposes the same documentation content as other public agent surfaces.
- An authentication callback can reject clients and may depend on an external identity system.
- OAuth protected-resource metadata remains public so clients can discover how to authenticate.

### Verification

- Run `pnpm exec docs doctor --agent`
  - Expected: MCP access and discovery/config/schema consistency pass.
- Initialize an MCP client and call list_docs followed by read_page for a known route.
  - Expected: The initialize request succeeds and both tools return structured content for the configured docs corpus.

### Rollback

- Set mcp.enabled to false, remove client configuration, and restore custom route or authentication wiring.

### Failure Modes

- The client receives 404 from /mcp or /.well-known/mcp. — Recovery: Align mcp.route with the framework public forwarder and keep the documented aliases pointing at the canonical handler.
- Every HTTP request receives 401 after authentication is enabled. — Recovery: Return a principal from security.authenticate for valid credentials and test the callback independently of MCP tools.
- Protected-resource metadata returns 404. — Recovery: Configure both security.authenticate and a non-empty protectedResource.authorizationServers list, then verify the public forwarder includes the metadata route.
- An authenticated client receives 403 insufficient_scope. — Recovery: Return all protectedResource.requiredScopes in the principal scopes, or narrow the endpoint-wide requirements.
<!-- farming-labs:agent-contract:end -->

# MCP Server

## MCP Server task

Task: Expose the docs MCP server over stdio or Streamable HTTP with optional explicit authentication.

Expected result: An MCP client initializes successfully and can discover, search, and read the configured documentation resources.

## MCP Server prerequisites

- The docs API and framework public forwarder are already wired.
- Choose stdio for local use or Streamable HTTP for a shared endpoint.
- Keep HTTP public by default and add security.authenticate only when the deployment requires access control.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## MCP Server verification

- Run pnpm exec docs doctor --agent. Expected: MCP access and discovery/config/schema consistency pass.
- Initialize an MCP client and call list_docs followed by read_page for a known route. Expected: The initialize request succeeds and both tools return structured content for the configured docs corpus.
- Failure: The client receives 404 from /mcp or /.well-known/mcp.
- Recovery: Align mcp.route with the framework public forwarder and keep the documented aliases pointing at the canonical handler.
- Rollback: Set mcp.enabled to false, remove client configuration, and restore custom route or authentication wiring.

## MCP Server agent guidance

MCP is enabled and public by default: `/mcp` and `/.well-known/mcp` forward to the canonical
`/api/docs/mcp` handler. Add `mcp.security.authenticate` only for private docs; return a principal to
continue or `null` for `401`. Add `mcp.security.protectedResource.authorizationServers` and scopes
only when OAuth-aware clients need RFC 9728 discovery.

Run `pnpm exec docs doctor --agent`, then initialize a client and call `list_docs` followed by
`read_page` for a known route. A `404` can mean MCP is disabled, static export omitted the server
route, or the canonical handler and public forwarder are missing or disagree; use doctor output to
distinguish them. Repeated `401` responses mean the callback is not returning a valid principal;
`403` with `insufficient_scope` means the principal lacks a configured required scope. Local-only
clients can avoid HTTP routing with `pnpm exec docs mcp`.

The public docs MCP never contains write tools. For an operator-controlled authoring session, run
`pnpm exec docs mcp author --branch-prefix docs/`. It restricts reads and writes to documentation
files under `contentDir`, requires a current SHA-256 before overwriting, and exposes branch,
preview, doctor, diff, and feedback-analysis tools. Draft-PR publishing is not registered unless the
operator also passes `--allow-publish`; keep that server on local stdio or behind a separate
authoring-scoped OAuth transport.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).