MCP Server

What is MCP?

Model Context Protocol (MCP) is an open standard from Anthropic that lets AI assistants connect to external data sources and tools through a unified interface.

Instead of pasting documentation into the chat, MCP lets the AI client search, browse, and read docs on demand. The AI queries documentation as needed rather than relying on stale training data.

What the gentleduck MCP server exposes

The server indexes the entire gentleduck documentation site — every package, every component, every changelog. Your agent can pull live information on:

• @gentleduck/registry-ui — 50+ styled Tailwind components.
• @gentleduck/primitives — headless ARIA-correct primitives.
• @gentleduck/calendar — calendar engine and date adapters.
• @gentleduck/cli — commands, flags, scaffolding behaviors.
• @gentleduck/vim — keyboard hooks and chord matching.
• @gentleduck/variants, @gentleduck/motion, @gentleduck/state, @gentleduck/hooks, @gentleduck/libs, @gentleduck/lazy.
• @gentleduck/iam, @gentleduck/upload, @gentleduck/query, @gentleduck/gen.
• The changelog and ecosystem-wide news posts.

The agent doesn't have to know about a specific package up front — it can discover what's available, read what's relevant, and stop pulling tokens for what it isn't using.

Why use it

• Reads live documentation instead of relying on training data.
• Token-efficient: get_component_api returns only the props table. Responses over 4000 chars are truncated with guidance for narrower queries.
• Fuzzy search handles typos ("buton" → "button").
• Ranked full-text search across the whole site.
• Filter by category — components, installation, packages, changelog, news.
• suggest_components matches a description to the best-fit component.
• CORS-enabled for browser-based MCP clients.
• Publicly available — no auth, just point your client at the URL.

Setup

Claude Desktop

{
  "mcpServers": {
    "gentleduck-docs": {
      "type": "url",
      "url": "https://gentleduck.org/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "gentleduck-docs": {
      "type": "url",
      "url": "https://gentleduck.org/api/mcp"
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code (CLI)

claude mcp add gentleduck-docs --transport http https://gentleduck.org/api/mcp

claude mcp add gentleduck-docs --transport http https://gentleduck.org/api/mcp

Cursor

Open Settings → MCP Servers → Add Server:

{
  "gentleduck-docs": {
    "url": "https://gentleduck.org/api/mcp"
  }
}

{
  "gentleduck-docs": {
    "url": "https://gentleduck.org/api/mcp"
  }
}

Windsurf

{
  "mcpServers": {
    "gentleduck-docs": {
      "serverUrl": "https://gentleduck.org/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "gentleduck-docs": {
      "serverUrl": "https://gentleduck.org/api/mcp"
    }
  }
}

Any MCP client

The server uses Streamable HTTP transport (the modern MCP standard). Any client that speaks MCP over HTTP can connect to:

https://gentleduck.org/api/mcp

For local development:

http://localhost:3000/api/mcp

Health probe (tool count, indexed docs/categories, cache age, active sessions):

https://gentleduck.org/api/mcp/health

Available tools

The server exposes nine tools, each designed to keep token usage down while giving the agent complete access to the documentation.

list_docs

Browse the documentation catalog with pagination. Returns a compact list of all pages with their slugs, titles, and descriptions.

"List all component docs from gentleduck" → list_docs({ category: "components" }) returns one line per component instead of dumping entire pages.

search_docs

Full-text search with typo tolerance across every package. Results are ranked by relevance — title matches score highest, then slug, then description, then body.

"Search the gentleduck docs for how to use loading states"

read_doc

Read a specific documentation page. The server strips all MDX/JSX syntax and returns clean markdown, so no tokens are wasted on <ComponentPreview> tags or import statements. Responses over 4000 chars are automatically truncated with a notice.

"Read the button component docs from duck-ui" "Show me just the API Reference section of the duck-primitives Dialog" "Give me a summary of the duck-calendar getting-started doc"

get_component_api

Shortcut that extracts only the props/API table from a component page. Most token-efficient way to look up component props. Suggests similar names if the input is misspelled.

"What props does the duck-ui Select component accept?"

get_examples

Get only the code examples from a documentation page. Returns all fenced code blocks without surrounding prose — saves tokens when you just need usage patterns.

get_changelog

Pull recent changelog entries across the whole organization, optionally filtered by package.

get_installation

Get the setup guide for a specific framework — Next.js, Vite, Astro, Remix, TanStack, Laravel, or manual.

suggest_components

Describe a need in natural language; receive a ranked list of components that match.

"I need something to show a confirmation modal that blocks the rest of the page" → returns Dialog, AlertDialog, with rationale.

semantic_search

TF-IDF-style natural language search across the indexed docs.

Putting it together

A typical agent flow looks like:

1. list_docs({ category: "components" }) to see what's available.
2. suggest_components({ query: "..." }) to pick the right one.
3. get_component_api({ component: "..." }) for the props.
4. get_examples({ slug: "..." }) for working code.

Four calls, ~1500 tokens total — much smaller than a single dump of the page would have been. The server is designed for this pattern: pull only what you're about to use, then move on.