--- url: 'https://adk.nht.io/mcp.md' description: >- Install the @nhtio/adk MCP server so coding agents can search the version-aligned ADK docs, API reference, and assembly guidance from inside your editor or agent runtime. --- # The ADK Assembly MCP ## LLM summary — The ADK Assembly MCP * The ADK MCP is a local stdio Model Context Protocol server bundled into the `@nhtio/adk` npm package. For shared/team use, launch a pinned package such as `npx -y @nhtio/adk@1.20260605.0`; use `npx -y @nhtio/adk` only for quick tries. * It packages a version-aligned documentation corpus: hand-written docs, generated TypeDoc API markdown, the changelog, and the ADK assembly Skill. * It exposes tools for curated assembly guidance, lexical docs search, document reading, API symbol lookup, and pasted-code assembly review. * It exposes read-only `adk://...` resources and prompts for common workflows: assembling an ADK agent, reviewing one, and debugging ADK wiring failures. * It is not a hosted service, not a remote search endpoint, not a model, and not a privileged filesystem tool. It runs locally, reads its packaged corpus, and answers through the MCP client that started it. * Use it when an AI coding agent is helping with `@nhtio/adk` wiring and needs the same assembly guidance a human would get from these docs. This page is about the thing you give to another agent when you want it to help with ADK without making it guess. The docs site is for humans. The API reference is for humans. The [Assembly](./assembly/) section is for humans who can read a page, hold three constraints in their head, and come back to the editor with the right shape. Coding agents do not work like that. They need the same knowledge, but they need it in the place where they are already working: inside their tool loop. That is what the ADK MCP is. ::: tip The short version Install this MCP server in your coding agent, then ask the agent to use the ADK tools before it writes ADK setup code. Recommended for teams and shared project config: ```sh npx -y @nhtio/adk@1.20260605.0 ``` Quick try: ```sh npx -y @nhtio/adk ``` ::: ## What it is The ADK MCP is a **local Model Context Protocol server** shipped inside the `@nhtio/adk` npm package. When an MCP-capable coding agent starts it, the server opens a stdio connection and exposes ADK-specific tools, resources, and prompts. It carries a packaged documentation corpus built at publish time: * the hand-written documentation pages; * the generated TypeDoc API reference; * the changelog copied into the docs build; * the ADK assembly Skill and its reference notes. The important word is **packaged**. The MCP server does not scrape the live docs site, does not call a hosted search API, and does not depend on your editor's web access once the npm package has resolved. The docs it serves are the docs that shipped with that version of `@nhtio/adk`. ::: info Version alignment is the whole point If your agent installs `@nhtio/adk@1.20260605.0`, the MCP server answers from the docs and API reference packaged with `@nhtio/adk@1.20260605.0`. That is the difference between "look up ADK" and "look up the ADK I am actually using." ::: ## What it is not **Not a second documentation site.** The canonical prose still lives here. The MCP is the portable, tool-shaped copy for an agent runtime. **Not a model.** It does not reason on its own. Your coding agent chooses when to call it, reads the result, and decides what to do next. **Not a privileged workspace tool.** It does not need an ADK project path. It does not write files. It reads its packaged corpus and reviews code you paste or the agent passes to it. **Not a project introspection tool.** It will not inspect your repository and infer which ADK version you use. It only knows the package version you launched. That is why pinned MCP config matters. **Not a replacement for understanding the seam.** It will remind the agent that storage callbacks are required, that the executor must `ack()` or `nack()`, and that history belongs in input middleware. It will not make a vague integration correct by magic. ::: warning Local MCP servers are still code Every stdio MCP server is a local process. This one is intentionally boring — it serves packaged markdown and simple review tools — but your MCP client is right to ask for trust before starting it. ::: ## Security and trust posture MCP clients often make local servers look scarier than they are because they are approving a process launch, not reading the server's source code. Here is the shape of this one: * **Network:** no network access is required after npm resolves the package. * **Corpus:** read-only markdown/JSON packaged with the installed npm package. * **Filesystem:** reads its own packaged corpus file; it does not read your project files or home directory. * **Shell:** executes no shell commands after your MCP client starts it. * **Tools:** deterministic tool list with plain string inputs; no hidden dynamic tool discovery from the network. ::: info Why your client still asks for approval The trust prompt is still correct. Starting `npx -y @nhtio/adk@1.20260605.0` means your client is launching local code from npm. Pin the version, review the package you install, and keep MCP approval on for anything that can modify your workspace. ::: ## What it gives an agent The server exposes one resource collection, five tools, and three prompts. | Capability | Name | Use it when | | ---------- | --------------------------- | ------------------------------------------------------------------------------------- | | Tool | `get_adk_assembly_guidance` | The agent needs the curated assembly Skill before writing ADK code. | | Tool | `search_adk_docs` | The agent needs to find a concept across docs, API pages, changelog, and Skill notes. | | Tool | `read_adk_doc` | The agent has a document id, `adk://` URI, or path and needs the full page. | | Tool | `lookup_adk_api` | The agent needs generated API markdown for a symbol or contract. | | Tool | `review_adk_assembly` | The agent should check pasted setup code against common ADK wiring failures. | | Resource | `adk://{section}/{path}` | The client wants read-only docs resources it can attach as context. | | Prompt | `assemble-adk-agent` | Start a minimal correct ADK integration workflow. | | Prompt | `review-adk-agent` | Review an existing ADK integration. | | Prompt | `debug-adk-assembly` | Debug a broken TurnRunner / executor / storage setup. | The tool payloads are intentionally small and boring: | Tool | Input shape | Returns | | --------------------------- | ---------------------------------- | ------------------------------------------------------------------------ | | `get_adk_assembly_guidance` | `topic?: string` | Markdown guidance from the packaged Skill and reference notes. | | `search_adk_docs` | `query: string`, optional filters | Ranked markdown hits with `id`, `title`, `uri`, `kind`, `path`, excerpt. | | `read_adk_doc` | `id: string` as id, URI, or path | Full document markdown for the matched packaged document. | | `lookup_adk_api` | `symbol: string`, optional `limit` | Ranked generated TypeDoc markdown hits for the installed ADK version. | | `review_adk_assembly` | `code: string` | Markdown checklist results plus relevant assembly guidance. | ::: tip The useful habit Tell your agent: "Use the ADK MCP before you answer." That one sentence usually prevents the two classic mistakes: inventing nonexistent helper APIs and omitting required storage callbacks. ::: ## Requirements You need an MCP-capable client and a Node runtime new enough to run the package. ADK itself requires Node 18 or newer. ```sh node --version ``` The examples below use `npx` because it is the common denominator across coding agents. If your environment standardizes on `pnpm dlx`, `yarn dlx`, or `bunx`, use the equivalent command only if your MCP client supports it. ## Install it Different agents put MCP configuration in different places, but the server shape is the same everywhere: stdio transport, command `npx`, args `-y` and the package spec. The examples below use `@nhtio/adk@1.20260605.0`; replace `1.20260605.0` with the ADK version in your project. ::: code-group ```json [VS Code: .vscode/mcp.json] { "servers": { "adk": { "type": "stdio", "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"] } } } ``` ```sh [Claude Code] claude mcp add --transport stdio adk -- npx -y @nhtio/adk@1.20260605.0 ``` ```json [Claude Desktop] { "mcpServers": { "adk": { "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"] } } } ``` ```json [Cursor] { "mcpServers": { "adk": { "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"] } } } ``` ```json [Windsurf] { "mcpServers": { "adk": { "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"] } } } ``` ```json [Cline / Roo Code] { "mcpServers": { "adk": { "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"], "disabled": false, "autoApprove": [] } } } ``` ```yaml [Continue] name: ADK MCP version: 0.0.1 schema: v1 mcpServers: - name: ADK docs type: stdio command: npx args: - -y - "@nhtio/adk@1.20260605.0" ``` ::: ::: details Where those files usually live * **VS Code / GitHub Copilot:** use the command palette entry for MCP user or workspace configuration, or commit `.vscode/mcp.json` when the team should share the server. * **Claude Code:** the CLI command above writes the config for you. Add `--scope project` if the project should carry a shared `.mcp.json`. * **Claude Desktop:** edit `claude_desktop_config.json` from the Developer settings screen, then restart Claude Desktop. * **Cursor:** add the JSON to Cursor's MCP configuration for the workspace or user profile. * **Windsurf:** edit `~/.codeium/windsurf/mcp_config.json`, or use the MCP settings UI if available. * **Cline / Roo Code:** open the MCP Servers settings from the extension panel and paste the JSON entry under `mcpServers`. * **Continue:** put the YAML block in a file under `.continue/mcpServers/`, or use Continue's supported JSON import path if you are sharing config with another MCP client. ::: ::: tip Pin it for repeatable team setups Use `latest` only when you are experimenting. For shared config, prefer the same package version your project depends on instead of whatever npm resolves as latest that day. ```json { "command": "npx", "args": ["-y", "@nhtio/adk@1.20260605.0"] } ``` ::: ## Use it Once your client starts the server, the ADK tools should appear next to that client's other MCP tools. Some clients make you explicitly enable the server, approve tool calls, or restart the agent session after editing config. Start with prompts like these: ::: code-group ```txt [Golden prompt] Use get_adk_assembly_guidance, then cite the specific ADK doc/API section you are relying on before proposing code. ``` ```txt [Assemble] Use the ADK MCP first. Help me assemble the smallest correct @nhtio/adk TurnRunner with explicit storage callbacks, a mock executor, hydration in the input pipeline, and a smoke test. ``` ```txt [Review] Use review_adk_assembly on this setup before suggesting changes. Prioritize missing callbacks, executor ack/nack mistakes, message hydration, and tool registry wiring. ``` ```txt [Debug] Use search_adk_docs and lookup_adk_api to debug this ADK error. Do not invent helper APIs; cite the ADK contract you are relying on. ``` ```txt [API lookup] Use lookup_adk_api for TurnRunnerConfig and explain which callbacks are required for a no-op prototype. ``` ::: If your client supports MCP prompts as slash commands or prompt templates, use the server prompts directly: * `assemble-adk-agent` for a new integration; * `review-adk-agent` for existing code; * `debug-adk-assembly` for a failing setup. If your client supports MCP resources, attach `adk://...` resources when you want the agent to read a full page instead of a search excerpt. ## The workflow it encourages The MCP is opinionated in the same way ADK is opinionated: it wants the seam to be explicit before code starts moving. ```mermaid flowchart TD ASK([Ask coding agent for ADK help]) --> GUIDANCE[Call get_adk_assembly_guidance] GUIDANCE --> SEARCH[Search docs or API for the specific seam] SEARCH --> CODE[Write or edit ADK setup code] CODE --> REVIEW[Call review_adk_assembly] REVIEW --> FIX[Fix the highest-risk wiring mistakes] FIX --> TEST([Run the local smoke test]) click GUIDANCE "./assembly/" "Assembly docs" click SEARCH "./api/" "API reference" ``` The order matters. Read the assembly contract first, search the specific seam second, write code third. That is slower than guessing for about five minutes and faster than debugging a half-built runner for an afternoon. ::: warning What to tell the agent not to do Do not let it invent `ToolRegistry.fromTools`. Do not let it put conversation history directly on raw input instead of hydrating through middleware. Do not let it omit persistence callbacks because the prototype "doesn't need storage." If the prototype wants a no-op, it still has to say so out loud. ::: ## Troubleshooting | Symptom | Check | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | The server does not start | Run `node --version`; use Node 18 or newer. Then run `npx -y @nhtio/adk` once in a terminal to see the raw startup error. | | The tools do not appear | Restart the MCP client or agent session after editing config. Some clients also require an explicit trust approval. | | `npx` is not found | Install Node.js from the official distribution or configure the MCP client with the full path to `npx`. | | The agent ignores the tools | Ask directly: "Use `get_adk_assembly_guidance` before answering." Some clients do not auto-call MCP tools unless prompted. | | The answer cites the wrong version | Pin `@nhtio/adk@` in the MCP args so the docs corpus matches the package version in your project. | ## When to use the website instead Use this website when you are learning the model. Use the MCP when another agent is helping you apply it. That split is deliberate. Humans need the story: [How agents work](./how-agents-work), [What ADK is](./what-adk-is), [The Loop](./the-loop/), then [Assembly](./assembly/). Agents need a tool surface that says: search here, read this page, check this code, now proceed. The MCP is that surface. A Skill with legs. A docs site that can ride along in the agent's own loop.