MCP integration (KDS for AI agents)

develop specs/develop/mcp-integration.kmd

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.

When this spec applies

Primary triggers

All triggers

KDS over MCP — agent integration

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

ToolUse
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 (component/pattern/token/foundation/preset/spec), optionally narrowed by a substring over name/summary/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.

References