The ADK Assembly MCP

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 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.

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:

npx -y @nhtio/adk@1.20260604.0

Quick try:

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.

Version alignment is the whole point

If your agent installs @nhtio/adk@1.20260604.0, the MCP server answers from the docs and API reference packaged with @nhtio/adk@1.20260604.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.

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.

Why your client still asks for approval

The trust prompt is still correct. Starting npx -y @nhtio/adk@1.20260604.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.

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.

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.20260604.0; replace 1.20260604.0 with the ADK version in your project.

VS Code: .vscode/mcp.json

{
	"servers": {
		"adk": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@nhtio/adk@1.20260604.0"]
		}
	}
}

Claude Code

claude mcp add --transport stdio adk -- npx -y @nhtio/adk@1.20260604.0

Claude Desktop

{
	"mcpServers": {
		"adk": {
			"command": "npx",
			"args": ["-y", "@nhtio/adk@1.20260604.0"]
		}
	}
}

Cursor

{
	"mcpServers": {
		"adk": {
			"command": "npx",
			"args": ["-y", "@nhtio/adk@1.20260604.0"]
		}
	}
}

Windsurf

{
	"mcpServers": {
		"adk": {
			"command": "npx",
			"args": ["-y", "@nhtio/adk@1.20260604.0"]
		}
	}
}

Cline / Roo Code

{
	"mcpServers": {
		"adk": {
			"command": "npx",
			"args": ["-y", "@nhtio/adk@1.20260604.0"],
			"disabled": false,
			"autoApprove": []
		}
	}
}

Continue

name: ADK MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: ADK docs
    type: stdio
    command: npx
    args:
      - -y
      - "@nhtio/adk@1.20260604.0"

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.

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.

{
	"command": "npx",
	"args": ["-y", "@nhtio/adk@1.20260604.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:

Golden prompt

Use get_adk_assembly_guidance, then cite the specific ADK doc/API section you
are relying on before proposing code.

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.

Review

Use review_adk_assembly on this setup before suggesting changes. Prioritize
missing callbacks, executor ack/nack mistakes, message hydration, and tool
registry wiring.

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.

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.

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.

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@<version> 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, What ADK is, The Loop, then 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.