MCP integration (KDS for AI agents)

How AI coding agents (Claude Code, Cursor, Codex, Windsurf) connect to the Koder Design System over Model Context Protocol. The KDS MCP server is live at `https://kds.koder.dev/mcp/` (streamable-http, anonymous, read-only) — query specs/tokens/components live instead of scraping HTML. Per design-RFC-010 + stack-RFC-002 §Auth carve-out.

The Koder Design System is reachable by AI coding agents over Model Context Protocol (MCP) at:

https://kds.koder.dev/mcp/

Transport: streamable-http (HTTP POST). Anonymous — no token, no login (the design system is public, read-only documentation per stack-RFC-002 §Auth carve-out). Discovery doc: https://kds.koder.dev/.well-known/mcp.json.

Setup

Claude Code

claude mcp add --transport http koder-design https://kds.koder.dev/mcp/

Cursor

Add to ~/.cursor/mcp.json (or the workspace .cursor/mcp.json):

{
  "mcpServers": {
    "koder-design": {
      "url": "https://kds.koder.dev/mcp/",
      "transport": "streamable-http"
    }
  }
}

Codex CLI / Windsurf / Continue

Any MCP client that speaks the 2025-06-18 streamable-http transport: point it at https://kds.koder.dev/mcp/, no auth header.

Tools

Tool Use
get_component(name) Fetch a component spec by friendly name (e.g. Button).
find_token(role) Tokens matching a semantic role.
list_patterns() All Koder Design patterns with summaries.
get_spec(id) Any spec entry by canonical ID (e.g. spec:themes-verge).
search(query) Fuzzy search across name + summary.
query_by_kind(kind, filter?) Items of a kind (componentpatterntokenfoundationpresetspec), optionally narrowed by a substring over namesummary/tags.

Resources

Every spec is also an MCP resource at URI kds://spec/<kind>/<slug> (e.g. kds://spec/component/components-button) — attach one as context without a tool call. resources/list enumerates them; resources/read returns the spec summary + canonical URLs + tags (the full rendered body lives at the page URL each resource carries).

Worked example

"Which KDS components have keyboard-navigation guidance?"

The agent calls query_by_kind(kind: "component", filter: "keyboard") over streamable-http and answers with the matching component names + their kds.koder.dev URLs — no HTML scrape, no local binary, no auth.

Notes

  • The server's knowledge base is the descriptor at

    https://kds.koder.dev/en-US/mcp/descriptor.json, refreshed on each KDS content deploy.

  • Local/offline use: the same engine ships in koder-design-lsp --mcp

    (stdio) for editors — claude mcp add koder-design /usr/local/bin/koder-design-lsp -- --mcp.

  • Prompts (the third MCP primitive) are out of scope for v0

    (stack-RFC-002); tools + resources cover agent discovery.