toolnexus 0.4.0 → 0.6.0

package/README.md

@@ -61,6 +61,41 @@ console.log(text)
 await tk.close()               // disconnect MCP servers
 ```
 
+## Suspension — login / approval / input (`Pending` / `waitFor`)
+
+Some tools can't finish in one shot: they need an **out-of-band, async resolution** — a human
+logs in, approves a trade, types a value. That's one idea, not one feature: *login* is just the
+`kind:"authorization"` case. A tool returns **`Pending(request)`**; the client calls your
+**`waitFor(request) → answer`**, then **retries the tool** with `ctx.answer`, and the model gets
+the real answer. Everything crossing a boundary is plain data, so it works the same across
+processes, agents, and restarts — and identically in all five language ports.
+
+```ts
+import { authRequired } from "toolnexus"
+
+// a tool that needs login the first time:
+defineTool({
+  name: "get_balance", description: "…", inputSchema: { type: "object", properties: {} },
+  run: (_args, ctx) =>
+    authed ? `balance: ₹67,417` : authRequired("https://example.com/login", "Log in to continue"),
+})
+
+// the host supplies ONE function — how the link reaches the human is your call:
+const agent = createClient({
+  baseUrl, style: "openai", model,
+  waitFor: async (request) => {          // interactive: open a browser + poll
+    open(request.url); await pollUntilLoggedIn(); return { id: request.id, ok: true }
+  },
+  // headless desk: waitFor = send request.url to your channel + poll
+  // another agent: waitFor = forward the request over A2A, await its answer
+})
+```
+
+Omit `waitFor` for a **durable** host: `run()` doesn't hang — it returns
+`{ status: "pending", pending: request }`, so you can deliver the link out-of-band (file, HTTP,
+channel) and resume later, even in another process. `stream()` emits a `{ type: "pending", request }`
+event so a channel can push the link in real time. Runnable demo: `examples/pending.ts`.
+
 ## Conversations / memory
 
 `run()` is stateless — each call starts fresh. To keep a thread's history, use `ask()` with an
@@ -268,6 +303,29 @@ Task persistence is a pluggable `TaskStore` — in-memory default, `"file:<dir>"
 it **remembers**: a message's A2A `contextId` keys the conversation through `client.ask`, so a
 peer's turns in the same context carry history via the client's `ConversationStore`.
 
+## Serve as an MCP server (be a gateway)
+
+The inbound mirror of A2A: expose your **whole toolkit as an MCP server** so any MCP client — an IDE,
+another agent, a remote host — can call its tools. Point toolnexus at N MCP servers + skills + your
+own functions, then re-expose the union as **one** MCP server. Unlike A2A (which advertises skills and
+runs the client loop), the MCP client *is* the LLM host, so each `tools/call` dispatches straight to
+`Tool.execute` — no `client`, no tasks, no store.
+
+```ts
+// streamable-HTTP — an embeddable MCP server mounted at POST /mcp, beside any A2A routes:
+const srv = await tk.serve("127.0.0.1:0", {
+  mcp: { name: "my-gateway" /*, tools: ["echo"]  // subset; omit ⇒ every toolkit tool */ },
+  onCall: (ev) => console.error(ev.name, ev.ms, ev.isError),
+})
+console.log(srv.url + "/mcp")   // connect any MCP client here
+await srv.stop()
+```
+
+`tools/list` advertises every toolkit tool (name **verbatim**, `inputSchema` = the tool's parameters);
+`mcp.tools` narrows the surface. The `mcp` profile can also live in the config file as a top-level
+**`mcpServer`** block (singular — distinct from the client-side `mcpServers`). (Transport is
+streamable-HTTP; a stdio transport for local clients like Claude Desktop is a planned follow-up.)
+
 ## Bring your own loop
 
 Don't want the host loop? Use the schema adapters and execute calls yourself:
@@ -309,7 +367,7 @@ a sixth.
 | `tk.skillsPrompt()` | system-prompt skill catalog |
 | `tk.mcpStatus()` | per-server connection status |
 | `tk.toOpenAI()` / `toAnthropic()` / `toGemini()` | provider tool schemas |
-| `tk.serve(addr, { client, a2a?, onTask? })` | serve the toolkit as an A2A agent → `ServeHandle` |
+| `tk.serve(addr, { client?, a2a?, onTask?, mcp?, onCall? })` | serve the toolkit over HTTP — A2A agent and/or streamable-HTTP MCP server (`/mcp`) → `ServeHandle` |
 | `tk.addAgent(cardUrl \| Agent)` | fetch a remote agent's card and register its skills as tools |
 | `tk.close()` | disconnect MCP servers |
 | `defineTool` / `httpTool` / `agent` | build native / HTTP / A2A tools |

package/dist/client.d.ts

@@ -4,7 +4,7 @@
  * Toolkit. See ../../SPEC.md §8.
  */
 import type { Toolkit } from "./toolkit.js";
-import type { ToolResult } from "./types.js";
+import type { ToolResult, Request, Answer } from "./types.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
     baseUrl: string;
@@ -27,6 +27,11 @@ export interface ClientOptions {
     /** Observability sink — receives semantic metric events ({event:"llm"|"tool"|"run"…}) as the
      * loop runs (§8 Observability). Forward to statsd/logs/OTel/anything. No cost when unset. */
     onMetric?: (ev: MetricEvent) => void;
+    /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
+     * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
+     * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
+     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+    waitFor?: (request: Request) => Promise<Answer>;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -148,6 +153,10 @@ export interface RunResult {
     usage: Usage;
     /** The model used. */
     model: string;
+    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
+    status: "done" | "pending";
+    /** The unresolved suspension — present iff status === "pending" (§10). */
+    pending?: Request;
 }
 /** Events yielded by client.stream(). */
 export type StreamEvent = {
@@ -167,6 +176,9 @@ export type StreamEvent = {
 } | {
     type: "usage";
     usage: Usage;
+} | {
+    type: "pending";
+    request: Request;
 } | {
     type: "done";
     result: RunResult;
@@ -229,6 +241,14 @@ export declare class Client {
     private llmCallJson;
     private runOpenAI;
     private result;
+    /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+    private pendingRun;
+    /**
+     * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+     * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+     * no `waitFor` is configured (the run should stop and surface the request).
+     */
+    private resolvePending;
     private runAnthropic;
     private streamOpenAI;
     private streamAnthropic;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { pendingOf } from "./types.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -342,12 +343,22 @@ export class Client {
                 if (calls.length === 0)
                     return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage);
                 // execute all tool calls in this turn concurrently (true parallel tool calling)
+                let halted;
                 const results = await Promise.all(calls.map(async (call) => {
-                    const { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
+                    let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
+                    const req = pendingOf(result);
+                    if (req) {
+                        const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn);
+                        result = r.result;
+                        if (r.halted)
+                            halted = r.halted;
+                    }
                     toolCalls.push({ name: call.function.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     return { role: "tool", tool_call_id: call.id, content: result.output };
                 }));
                 messages.push(...results);
+                if (halted)
+                    return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }
             return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage);
         }
@@ -357,7 +368,35 @@ export class Client {
         }
     }
     result(text, messages, toolCalls, turns, usage) {
-        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model };
+        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" };
+    }
+    /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+    pendingRun(runStart, request, messages, toolCalls, turns, usage) {
+        this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
+        return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "pending", pending: request };
+    }
+    /**
+     * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+     * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+     * no `waitFor` is configured (the run should stop and surface the request).
+     */
+    async resolvePending(toolkit, name, args, request, id, turn) {
+        if (!this.opts.waitFor)
+            return { result: { output: request.prompt, isError: true }, halted: request };
+        const answer = await this.opts.waitFor(request);
+        if (!answer?.ok)
+            return { result: { output: `declined/expired: ${request.prompt}`, isError: true } };
+        const t0 = Date.now();
+        let result = await toolkit.execute(name, args, { answer });
+        if (this.opts.hooks?.afterTool) {
+            const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn });
+            if (ov?.result)
+                result = ov.result;
+        }
+        this.emit({ event: "tool", tool: name, source: toolkit.get(name)?.source ?? "custom", isError: result.isError, ms: Date.now() - t0 });
+        if (pendingOf(result))
+            result = { output: `unresolved: ${request.prompt}`, isError: true }; // never loop forever
+        return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
     async runAnthropic(prompt, toolkit, external, history) {
@@ -402,12 +441,22 @@ export class Client {
                     return this.endRun(runStart, text, messages, toolCalls, turns, usage);
                 }
                 // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
+                let halted;
                 const results = await Promise.all(uses.map(async (use) => {
-                    const { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
+                    let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
+                    const req = pendingOf(result);
+                    if (req) {
+                        const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn);
+                        result = r.result;
+                        if (r.halted)
+                            halted = r.halted;
+                    }
                     toolCalls.push({ name: use.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     return { type: "tool_result", tool_use_id: use.id, content: result.output, is_error: result.isError };
                 }));
                 messages.push({ role: "user", content: results });
+                if (halted)
+                    return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }
             return this.endRun(runStart, "", messages, toolCalls, turns, usage);
         }
@@ -500,7 +549,20 @@ export class Client {
                     yield { type: "tool_call", id: c.id, name: c.name, args: safeJson(c.args) };
                 const settled = await Promise.all(calls.map((c) => this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn)));
                 for (let i = 0; i < calls.length; i++) {
-                    const c = calls[i], { args, result } = settled[i];
+                    const c = calls[i];
+                    let { args, result } = settled[i];
+                    const req = pendingOf(result);
+                    if (req) {
+                        yield { type: "pending", request: req }; // surface BEFORE waitFor so a channel can push the link
+                        const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn);
+                        result = r.result;
+                        if (r.halted) {
+                            toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
+                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            return;
+                        }
+                    }
                     toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
@@ -594,7 +656,21 @@ export class Client {
                 const settled = await Promise.all(uses.map((u) => this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn)));
                 const results = [];
                 for (let i = 0; i < uses.length; i++) {
-                    const u = uses[i], { args, result } = settled[i];
+                    const u = uses[i];
+                    let { args, result } = settled[i];
+                    const req = pendingOf(result);
+                    if (req) {
+                        yield { type: "pending", request: req };
+                        const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn);
+                        result = r.result;
+                        if (r.halted) {
+                            toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
+                            messages.push({ role: "user", content: results });
+                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            return;
+                        }
+                    }
                     toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
                     yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./serve.js";
+export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
 export * from "./serve.js";
+export * from "./mcpserve.js";
 export * from "./adapters.js";
 export * from "./toolkit.js";
 export * from "./client.js";

package/dist/mcp.js

@@ -32,9 +32,9 @@ export function parseMcpConfig(input) {
     if (wrapped !== undefined)
         return wrapped;
     // Bare map of servers — but strip sibling top-level config keys (builtins/
-    // agents/a2a) so they are not mistaken for MCP servers when no wrapper key
-    // is present.
-    const { builtins: _builtins, agents: _agents, a2a: _a2a, ...servers } = raw;
+    // agents/a2a/mcpServer) so they are not mistaken for MCP servers when no
+    // wrapper key is present.
+    const { builtins: _builtins, agents: _agents, a2a: _a2a, mcpServer: _mcpServer, ...servers } = raw;
     return servers;
 }
 /**

package/dist/mcpserve.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP — INBOUND: serve a toolkit as an MCP server (SPEC §7C).
+ *
+ * The inbound mirror of the A2A `serve` (§7B). Where A2A advertises the toolkit's
+ * **skills** and fulfils a Task through the whole client loop, MCP advertises the
+ * toolkit's **unified tools** (every source — mcp · skill · native · http ·
+ * builtin · a2a) and dispatches each `tools/call` straight to `Tool.execute`. The
+ * calling MCP client *is* the LLM host, so there is **no client, no Task, and no
+ * TaskStore** — just `tools/list` + `tools/call` over the toolkit registry.
+ *
+ * Transport: **streamable-HTTP**, mounted at `POST /mcp` on the `serve(addr, …)`
+ * server alongside the A2A routes (see serve.ts), built on the same
+ * `@modelcontextprotocol/sdk` the client side already uses.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Tool, ToolSource } from "./types.js";
+/** Opt-in MCP serve profile — the toolkit is exposed as an MCP server. */
+export interface MCPServeConfig {
+    /** Advertised server name (initialize `serverInfo.name`). Default "toolnexus". */
+    name?: string;
+    /** Advertised server version. Default "0.1.0". */
+    version?: string;
+    /** Subset of tool names to expose; omit ⇒ all. Unknown names are ignored. */
+    tools?: string[];
+}
+/** Surfaced on each inbound `tools/call`. */
+export interface OnCallEvent {
+    name: string;
+    source: ToolSource;
+    ms: number;
+    isError: boolean;
+}
+export type OnCall = (ev: OnCallEvent) => void | Promise<void>;
+/**
+ * The tools this profile exposes: every toolkit tool, filtered to `cfg.tools`
+ * when set (unknown names in the filter are ignored, never an error).
+ */
+export declare function exposedMcpTools(tools: Tool[], cfg?: MCPServeConfig): Tool[];
+/**
+ * Build a low-level MCP `Server` exposing `tools` as MCP tools. `tools/list`
+ * maps each Tool's name (verbatim — already sanitized at registration),
+ * description, and inputSchema; `tools/call` dispatches to `Tool.execute` and
+ * maps the `ToolResult` to a `CallToolResult` (`output` → text, `isError`
+ * propagates). A fresh server is cheap to build, so the HTTP path makes one per
+ * request (stateless).
+ */
+export declare function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnCall): Server;

package/dist/mcpserve.js

@@ -0,0 +1,69 @@
+/**
+ * MCP — INBOUND: serve a toolkit as an MCP server (SPEC §7C).
+ *
+ * The inbound mirror of the A2A `serve` (§7B). Where A2A advertises the toolkit's
+ * **skills** and fulfils a Task through the whole client loop, MCP advertises the
+ * toolkit's **unified tools** (every source — mcp · skill · native · http ·
+ * builtin · a2a) and dispatches each `tools/call` straight to `Tool.execute`. The
+ * calling MCP client *is* the LLM host, so there is **no client, no Task, and no
+ * TaskStore** — just `tools/list` + `tools/call` over the toolkit registry.
+ *
+ * Transport: **streamable-HTTP**, mounted at `POST /mcp` on the `serve(addr, …)`
+ * server alongside the A2A routes (see serve.ts), built on the same
+ * `@modelcontextprotocol/sdk` the client side already uses.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+const DEFAULT_NAME = "toolnexus";
+const DEFAULT_VERSION = "0.1.0";
+/**
+ * The tools this profile exposes: every toolkit tool, filtered to `cfg.tools`
+ * when set (unknown names in the filter are ignored, never an error).
+ */
+export function exposedMcpTools(tools, cfg) {
+    if (!cfg?.tools)
+        return tools;
+    const wanted = new Set(cfg.tools);
+    return tools.filter((t) => wanted.has(t.name));
+}
+/**
+ * Build a low-level MCP `Server` exposing `tools` as MCP tools. `tools/list`
+ * maps each Tool's name (verbatim — already sanitized at registration),
+ * description, and inputSchema; `tools/call` dispatches to `Tool.execute` and
+ * maps the `ToolResult` to a `CallToolResult` (`output` → text, `isError`
+ * propagates). A fresh server is cheap to build, so the HTTP path makes one per
+ * request (stateless).
+ */
+export function buildMcpServer(tools, cfg, onCall) {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const server = new Server({ name: cfg?.name ?? DEFAULT_NAME, version: cfg?.version ?? DEFAULT_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        const tool = byName.get(req.params.name);
+        if (!tool)
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
+        const started = Date.now();
+        // The call is a single synchronous tool invocation honoring the MCP
+        // request's cancellation. An execute() throw becomes an isError result —
+        // never a crash.
+        let result;
+        try {
+            result = await tool.execute(req.params.arguments ?? {}, { signal: extra.signal });
+        }
+        catch (e) {
+            result = { output: e instanceof Error ? e.message : String(e), isError: true };
+        }
+        if (onCall) {
+            try {
+                await onCall({ name: tool.name, source: tool.source, ms: Date.now() - started, isError: result.isError });
+            }
+            catch {
+                // Host callback errors are isolated.
+            }
+        }
+        return { content: [{ type: "text", text: result.output }], isError: result.isError };
+    });
+    return server;
+}

package/dist/serve.d.ts

@@ -1,6 +1,8 @@
+import { type Tool } from "./types.js";
 import type { SkillInfo } from "./skill.js";
 import type { RunResult } from "./client.js";
 import type { A2ATask, A2ATaskState, AgentCard } from "./a2a.js";
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
 /** Pluggable Task persistence. The-factory can plug NATS/JetStream the same way. */
 export interface TaskStore {
     get(id: string): Promise<A2ATask | undefined>;
@@ -71,6 +73,12 @@ export interface StartServerOptions {
      * message) keys the conversation so served turns are remembered via the store. */
     runTask: (text: string, contextId?: string) => Promise<RunResult>;
     onTask?: OnTask;
+    /** When present, mounts a streamable-HTTP MCP server at `/mcp`; absent ⇒ no MCP route. */
+    mcp?: MCPServeConfig;
+    /** The toolkit's unified tools, exposed by the MCP profile. */
+    mcpTools?: Tool[];
+    /** Surfaced on each inbound MCP `tools/call`. */
+    onCall?: OnCall;
 }
 /**
  * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,

package/dist/serve.js

@@ -18,7 +18,9 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { sanitize } from "./types.js";
+import { buildMcpServer, exposedMcpTools } from "./mcpserve.js";
 /** Default in-memory store — Tasks live only for the lifetime of the process. */
 export class InMemoryTaskStore {
     tasks = new Map();
@@ -111,14 +113,23 @@ function readBody(req) {
         req.on("end", () => resolve(body));
     });
 }
+function safeJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,
  * the server answers 404 to everything (a minimal base for now).
  */
 export async function startA2AServer(opts) {
-    const { a2a, skills, runTask, onTask } = opts;
+    const { a2a, skills, runTask, onTask, mcp, mcpTools, onCall } = opts;
     const [host, portStr] = splitAddr(opts.addr);
     const store = a2a ? resolveStore(a2a.store) : undefined;
+    const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : [];
     const server = http.createServer((req, res) => {
         const rpcRes = (id, payload) => {
             res.writeHead(200, { "content-type": "application/json" });
@@ -126,7 +137,36 @@ export async function startA2AServer(opts) {
         };
         const rpcOk = (id, result) => rpcRes(id, { result });
         const rpcErr = (id, code, message) => rpcRes(id, { error: { code, message } });
-        // No A2A profile ⇒ no routes.
+        // No profile at all ⇒ no routes.
+        if (!store && !mcp) {
+            res.writeHead(404);
+            res.end("not found");
+            return;
+        }
+        // MCP streamable-HTTP profile (independent of A2A): a fresh server+transport
+        // per request (stateless — sessionIdGenerator undefined). Checked first so
+        // `/mcp` is never shadowed by the A2A POST handler.
+        if (mcp && req.url && (req.url === "/mcp" || req.url.startsWith("/mcp?"))) {
+            void (async () => {
+                const body = req.method === "POST" ? await readBody(req) : "";
+                const parsed = body ? safeJson(body) : undefined;
+                const mcpServer = buildMcpServer(exposedTools, mcp, onCall);
+                const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+                res.on("close", () => {
+                    void transport.close();
+                    void mcpServer.close();
+                });
+                await mcpServer.connect(transport);
+                await transport.handleRequest(req, res, parsed);
+            })().catch(() => {
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end("mcp error");
+                }
+            });
+            return;
+        }
+        // No A2A profile ⇒ no A2A routes (an MCP-only server 404s everything else).
         if (!a2a || !store) {
             res.writeHead(404);
             res.end("not found");

package/dist/toolkit.d.ts

@@ -6,6 +6,7 @@ import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./
 import { type BuiltinsConfig } from "./builtin.js";
 import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js";
 import type { Client } from "./client.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
@@ -21,6 +22,8 @@ export declare class Toolkit {
     private readonly skill;
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     private readonly a2aConfig;
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    private readonly mcpServerConfig;
     private byName;
     private constructor();
     static create(opts: ToolkitOptions): Promise<Toolkit>;
@@ -43,9 +46,11 @@ export declare class Toolkit {
      * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
      */
     serve(addr: string, opts: {
-        client: Client;
+        client?: Client;
         a2a?: A2AConfig;
         onTask?: OnTask;
+        mcp?: MCPServeConfig;
+        onCall?: OnCall;
     }): Promise<ServeHandle>;
     execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
     /** Markdown skill catalog for the system prompt. */

package/dist/toolkit.js

@@ -8,13 +8,17 @@ export class Toolkit {
     mcp;
     skill;
     a2aConfig;
+    mcpServerConfig;
     byName = new Map();
     constructor(mcp, skill, builtins, agents, extraTools, 
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
-    a2aConfig) {
+    a2aConfig, 
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    mcpServerConfig) {
         this.mcp = mcp;
         this.skill = skill;
         this.a2aConfig = a2aConfig;
+        this.mcpServerConfig = mcpServerConfig;
         // Builtins are the lowest-precedence source: a host extraTools entry with
         // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
         // front, then apply the normal first-wins dedupe for MCP/skill/agents/extras.
@@ -60,7 +64,14 @@ export class Toolkit {
         if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "a2a" in opts.mcpConfig) {
             a2aConfig = opts.mcpConfig.a2a;
         }
-        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig);
+        // MCP inbound profile: a top-level `mcpServer` (singular) block — distinct
+        // from the client-side `mcpServers` block. serve()/serveStdio() prefer their
+        // inline `mcp` over this.
+        let mcpServerConfig;
+        if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
+            mcpServerConfig = opts.mcpConfig.mcpServer;
+        }
+        return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig);
     }
     tools() {
         return [...this.byName.values()];
@@ -99,6 +110,7 @@ export class Toolkit {
      */
     serve(addr, opts) {
         const a2a = opts.a2a ?? this.a2aConfig;
+        const mcp = opts.mcp ?? this.mcpServerConfig;
         const skills = this.skill ? Object.values(this.skill.skills) : [];
         return startA2AServer({
             addr,
@@ -108,6 +120,9 @@ export class Toolkit {
                 ? opts.client.ask(text, { toolkit: this, id: contextId })
                 : opts.client.run(text, { toolkit: this }),
             onTask: opts.onTask,
+            mcp,
+            mcpTools: mcp ? this.tools() : undefined,
+            onCall: opts.onCall,
         });
     }
     async execute(name, args, ctx) {

package/dist/types.d.ts

@@ -17,7 +17,35 @@ export interface ToolResult {
 export interface ToolContext {
     signal?: AbortSignal;
     timeout?: number;
+    /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
+    answer?: Answer;
 }
+/**
+ * §10 Suspension. A tool that needs an out-of-band, async resolution (login, approval,
+ * input) returns a normal ToolResult carrying `metadata.pending = Request`. Byte-identical
+ * wire data — it crosses languages, processes, and agents unchanged.
+ */
+export interface Request {
+    id: string;
+    kind: string;
+    prompt: string;
+    url?: string;
+    data?: Record<string, unknown>;
+    expiresAt?: string;
+}
+export interface Answer {
+    id: string;
+    ok: boolean;
+    data?: Record<string, unknown>;
+}
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export declare function pending(request: Omit<Request, "id"> & {
+    id?: string;
+}): ToolResult;
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export declare function authRequired(url: string, prompt?: string): ToolResult;
+/** Read the suspension off a result, if any. */
+export declare function pendingOf(result: ToolResult): Request | undefined;
 export interface Tool {
     name: string;
     description: string;

package/dist/types.js

@@ -1,5 +1,24 @@
 /**
  * Shared contract types. See ../../SPEC.md.
  */
+let _pendingSeq = 0;
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export function pending(request) {
+    const id = request.id ?? `pnd-${Date.now().toString(36)}-${++_pendingSeq}`;
+    const req = { ...request, id };
+    return {
+        output: req.prompt + (req.url ? `\n${req.url}` : ""),
+        isError: true,
+        metadata: { pending: req },
+    };
+}
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export function authRequired(url, prompt = "Authorization required to continue") {
+    return pending({ kind: "authorization", prompt, url });
+}
+/** Read the suspension off a result, if any. */
+export function pendingOf(result) {
+    return result.metadata?.pending;
+}
 /** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */
 export const sanitize = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "_");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -4,7 +4,8 @@
  * Toolkit. See ../../SPEC.md §8.
  */
 import type { Toolkit } from "./toolkit.js"
-import type { ToolResult } from "./types.js"
+import type { ToolResult, Request, Answer } from "./types.js"
+import { pendingOf } from "./types.js"
 
 export type ClientStyle = "openai" | "anthropic"
 
@@ -29,6 +30,11 @@ export interface ClientOptions {
   /** Observability sink — receives semantic metric events ({event:"llm"|"tool"|"run"…}) as the
    * loop runs (§8 Observability). Forward to statsd/logs/OTel/anything. No cost when unset. */
   onMetric?: (ev: MetricEvent) => void
+  /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
+   * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
+   * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
+   * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+  waitFor?: (request: Request) => Promise<Answer>
 }
 
 /**
@@ -117,6 +123,10 @@ export interface RunResult {
   usage: Usage
   /** The model used. */
   model: string
+  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
+  status: "done" | "pending"
+  /** The unresolved suspension — present iff status === "pending" (§10). */
+  pending?: Request
 }
 
 /** Events yielded by client.stream(). */
@@ -125,6 +135,7 @@ export type StreamEvent =
   | { type: "tool_call"; id: string; name: string; args: Record<string, unknown> }
   | { type: "tool_result"; id: string; name: string; output: string; isError: boolean }
   | { type: "usage"; usage: Usage }
+  | { type: "pending"; request: Request }
   | { type: "done"; result: RunResult }
 
 function addUsage(acc: Usage, raw: any, style: ClientStyle): void {
@@ -458,14 +469,22 @@ export class Client {
         const calls = msg.tool_calls ?? []
         if (calls.length === 0) return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage)
         // execute all tool calls in this turn concurrently (true parallel tool calling)
+        let halted: Request | undefined
         const results = await Promise.all(
           calls.map(async (call: any) => {
-            const { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn)
+            let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn)
+            const req = pendingOf(result)
+            if (req) {
+              const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn)
+              result = r.result
+              if (r.halted) halted = r.halted
+            }
             toolCalls.push({ name: call.function.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
             return { role: "tool", tool_call_id: call.id, content: result.output }
           }),
         )
         messages.push(...results)
+        if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
       }
       return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage)
     } catch (e) {
@@ -475,7 +494,35 @@ export class Client {
   }
 
   private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
-    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model }
+    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" }
+  }
+
+  /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+  private pendingRun(runStart: number, request: Request, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
+    this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart })
+    return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "pending", pending: request }
+  }
+
+  /**
+   * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+   * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+   * no `waitFor` is configured (the run should stop and surface the request).
+   */
+  private async resolvePending(
+    toolkit: Toolkit, name: string, args: Record<string, unknown>, request: Request, id: string | undefined, turn: number,
+  ): Promise<{ result: ToolResult; halted?: Request }> {
+    if (!this.opts.waitFor) return { result: { output: request.prompt, isError: true }, halted: request }
+    const answer = await this.opts.waitFor(request)
+    if (!answer?.ok) return { result: { output: `declined/expired: ${request.prompt}`, isError: true } }
+    const t0 = Date.now()
+    let result = await toolkit.execute(name, args, { answer })
+    if (this.opts.hooks?.afterTool) {
+      const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn })
+      if (ov?.result) result = ov.result
+    }
+    this.emit({ event: "tool", tool: name, source: toolkit.get(name)?.source ?? "custom", isError: result.isError, ms: Date.now() - t0 })
+    if (pendingOf(result)) result = { output: `unresolved: ${request.prompt}`, isError: true } // never loop forever
+    return { result }
   }
 
   // ---- Anthropic-style: POST {baseUrl}/messages ----
@@ -519,14 +566,22 @@ export class Client {
           return this.endRun(runStart, text, messages, toolCalls, turns, usage)
         }
         // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
+        let halted: Request | undefined
         const results = await Promise.all(
           uses.map(async (use: any) => {
-            const { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn)
+            let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn)
+            const req = pendingOf(result)
+            if (req) {
+              const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn)
+              result = r.result
+              if (r.halted) halted = r.halted
+            }
             toolCalls.push({ name: use.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
             return { type: "tool_result", tool_use_id: use.id, content: result.output, is_error: result.isError }
           }),
         )
         messages.push({ role: "user", content: results })
+        if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
       }
       return this.endRun(runStart, "", messages, toolCalls, turns, usage)
     } catch (e) {
@@ -605,7 +660,20 @@ export class Client {
         for (const c of calls) yield { type: "tool_call", id: c.id, name: c.name, args: safeJson(c.args) }
         const settled = await Promise.all(calls.map((c) => this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn)))
         for (let i = 0; i < calls.length; i++) {
-          const c = calls[i], { args, result } = settled[i]
+          const c = calls[i]
+          let { args, result } = settled[i]
+          const req = pendingOf(result)
+          if (req) {
+            yield { type: "pending", request: req } // surface BEFORE waitFor so a channel can push the link
+            const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn)
+            result = r.result
+            if (r.halted) {
+              toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+              yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
+              return
+            }
+          }
           toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
           messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
@@ -683,7 +751,21 @@ export class Client {
         const settled = await Promise.all((uses as any[]).map((u) => this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn)))
         const results: any[] = []
         for (let i = 0; i < uses.length; i++) {
-          const u = uses[i] as any, { args, result } = settled[i]
+          const u = uses[i] as any
+          let { args, result } = settled[i]
+          const req = pendingOf(result)
+          if (req) {
+            yield { type: "pending", request: req }
+            const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn)
+            result = r.result
+            if (r.halted) {
+              toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+              messages.push({ role: "user", content: results })
+              yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
+              return
+            }
+          }
           toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
           results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
           yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError }

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./native.js"
 export * from "./http.js"
 export * from "./a2a.js"
 export * from "./serve.js"
+export * from "./mcpserve.js"
 export * from "./adapters.js"
 export * from "./toolkit.js"
 export * from "./client.js"

package/src/mcp.ts

@@ -55,9 +55,9 @@ export function parseMcpConfig(input: string | object): McpConfig {
   const wrapped = raw.mcpServers ?? raw.servers ?? raw.mcp
   if (wrapped !== undefined) return wrapped as McpConfig
   // Bare map of servers — but strip sibling top-level config keys (builtins/
-  // agents/a2a) so they are not mistaken for MCP servers when no wrapper key
-  // is present.
-  const { builtins: _builtins, agents: _agents, a2a: _a2a, ...servers } = raw
+  // agents/a2a/mcpServer) so they are not mistaken for MCP servers when no
+  // wrapper key is present.
+  const { builtins: _builtins, agents: _agents, a2a: _a2a, mcpServer: _mcpServer, ...servers } = raw
   return servers as McpConfig
 }
 

package/src/mcpserve.ts

@@ -0,0 +1,95 @@
+/**
+ * MCP — INBOUND: serve a toolkit as an MCP server (SPEC §7C).
+ *
+ * The inbound mirror of the A2A `serve` (§7B). Where A2A advertises the toolkit's
+ * **skills** and fulfils a Task through the whole client loop, MCP advertises the
+ * toolkit's **unified tools** (every source — mcp · skill · native · http ·
+ * builtin · a2a) and dispatches each `tools/call` straight to `Tool.execute`. The
+ * calling MCP client *is* the LLM host, so there is **no client, no Task, and no
+ * TaskStore** — just `tools/list` + `tools/call` over the toolkit registry.
+ *
+ * Transport: **streamable-HTTP**, mounted at `POST /mcp` on the `serve(addr, …)`
+ * server alongside the A2A routes (see serve.ts), built on the same
+ * `@modelcontextprotocol/sdk` the client side already uses.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js"
+import type { Tool, ToolSource } from "./types.js"
+
+const DEFAULT_NAME = "toolnexus"
+const DEFAULT_VERSION = "0.1.0"
+
+/** Opt-in MCP serve profile — the toolkit is exposed as an MCP server. */
+export interface MCPServeConfig {
+  /** Advertised server name (initialize `serverInfo.name`). Default "toolnexus". */
+  name?: string
+  /** Advertised server version. Default "0.1.0". */
+  version?: string
+  /** Subset of tool names to expose; omit ⇒ all. Unknown names are ignored. */
+  tools?: string[]
+}
+
+/** Surfaced on each inbound `tools/call`. */
+export interface OnCallEvent {
+  name: string
+  source: ToolSource
+  ms: number
+  isError: boolean
+}
+
+export type OnCall = (ev: OnCallEvent) => void | Promise<void>
+
+/**
+ * The tools this profile exposes: every toolkit tool, filtered to `cfg.tools`
+ * when set (unknown names in the filter are ignored, never an error).
+ */
+export function exposedMcpTools(tools: Tool[], cfg?: MCPServeConfig): Tool[] {
+  if (!cfg?.tools) return tools
+  const wanted = new Set(cfg.tools)
+  return tools.filter((t) => wanted.has(t.name))
+}
+
+/**
+ * Build a low-level MCP `Server` exposing `tools` as MCP tools. `tools/list`
+ * maps each Tool's name (verbatim — already sanitized at registration),
+ * description, and inputSchema; `tools/call` dispatches to `Tool.execute` and
+ * maps the `ToolResult` to a `CallToolResult` (`output` → text, `isError`
+ * propagates). A fresh server is cheap to build, so the HTTP path makes one per
+ * request (stateless).
+ */
+export function buildMcpServer(tools: Tool[], cfg?: MCPServeConfig, onCall?: OnCall): Server {
+  const byName = new Map(tools.map((t) => [t.name, t]))
+  const server = new Server(
+    { name: cfg?.name ?? DEFAULT_NAME, version: cfg?.version ?? DEFAULT_VERSION },
+    { capabilities: { tools: {} } },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+    const tool = byName.get(req.params.name)
+    if (!tool) throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`)
+    const started = Date.now()
+    // The call is a single synchronous tool invocation honoring the MCP
+    // request's cancellation. An execute() throw becomes an isError result —
+    // never a crash.
+    let result
+    try {
+      result = await tool.execute(req.params.arguments ?? {}, { signal: extra.signal })
+    } catch (e) {
+      result = { output: e instanceof Error ? e.message : String(e), isError: true }
+    }
+    if (onCall) {
+      try {
+        await onCall({ name: tool.name, source: tool.source, ms: Date.now() - started, isError: result.isError })
+      } catch {
+        // Host callback errors are isolated.
+      }
+    }
+    return { content: [{ type: "text", text: result.output }], isError: result.isError }
+  })
+
+  return server
+}

package/src/serve.ts

@@ -18,10 +18,12 @@ import http from "node:http"
 import fs from "node:fs"
 import path from "node:path"
 import { randomUUID } from "node:crypto"
-import { sanitize } from "./types.js"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+import { sanitize, type Tool } from "./types.js"
 import type { SkillInfo } from "./skill.js"
 import type { RunResult } from "./client.js"
 import type { A2AArtifact, A2ATask, A2ATaskState, AgentCard } from "./a2a.js"
+import { buildMcpServer, exposedMcpTools, type MCPServeConfig, type OnCall } from "./mcpserve.js"
 
 // ---------------------------------------------------------------------------
 // TaskStore adapter — pluggable persistence for served Tasks.
@@ -162,6 +164,12 @@ export interface StartServerOptions {
    * message) keys the conversation so served turns are remembered via the store. */
   runTask: (text: string, contextId?: string) => Promise<RunResult>
   onTask?: OnTask
+  /** When present, mounts a streamable-HTTP MCP server at `/mcp`; absent ⇒ no MCP route. */
+  mcp?: MCPServeConfig
+  /** The toolkit's unified tools, exposed by the MCP profile. */
+  mcpTools?: Tool[]
+  /** Surfaced on each inbound MCP `tools/call`. */
+  onCall?: OnCall
 }
 
 /** Extract the concatenated text of a JSON-RPC `SendMessage` message's parts. */
@@ -182,14 +190,23 @@ function readBody(req: http.IncomingMessage): Promise<string> {
   })
 }
 
+function safeJson(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Start the HTTP server. Delegated to by `Toolkit.serve`. When `a2a` is absent,
  * the server answers 404 to everything (a minimal base for now).
  */
 export async function startA2AServer(opts: StartServerOptions): Promise<ServeHandle> {
-  const { a2a, skills, runTask, onTask } = opts
+  const { a2a, skills, runTask, onTask, mcp, mcpTools, onCall } = opts
   const [host, portStr] = splitAddr(opts.addr)
   const store = a2a ? resolveStore(a2a.store) : undefined
+  const exposedTools = mcp ? exposedMcpTools(mcpTools ?? [], mcp) : []
 
   const server = http.createServer((req, res) => {
     const rpcRes = (id: unknown, payload: object) => {
@@ -199,7 +216,38 @@ export async function startA2AServer(opts: StartServerOptions): Promise<ServeHan
     const rpcOk = (id: unknown, result: unknown) => rpcRes(id, { result })
     const rpcErr = (id: unknown, code: number, message: string) => rpcRes(id, { error: { code, message } })
 
-    // No A2A profile ⇒ no routes.
+    // No profile at all ⇒ no routes.
+    if (!store && !mcp) {
+      res.writeHead(404)
+      res.end("not found")
+      return
+    }
+
+    // MCP streamable-HTTP profile (independent of A2A): a fresh server+transport
+    // per request (stateless — sessionIdGenerator undefined). Checked first so
+    // `/mcp` is never shadowed by the A2A POST handler.
+    if (mcp && req.url && (req.url === "/mcp" || req.url.startsWith("/mcp?"))) {
+      void (async () => {
+        const body = req.method === "POST" ? await readBody(req) : ""
+        const parsed = body ? safeJson(body) : undefined
+        const mcpServer = buildMcpServer(exposedTools, mcp, onCall)
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+        res.on("close", () => {
+          void transport.close()
+          void mcpServer.close()
+        })
+        await mcpServer.connect(transport)
+        await transport.handleRequest(req, res, parsed)
+      })().catch(() => {
+        if (!res.headersSent) {
+          res.writeHead(500)
+          res.end("mcp error")
+        }
+      })
+      return
+    }
+
+    // No A2A profile ⇒ no A2A routes (an MCP-only server 404s everything else).
     if (!a2a || !store) {
       res.writeHead(404)
       res.end("not found")

package/src/toolkit.ts

@@ -8,6 +8,7 @@ import { loadSkills, type SkillSource } from "./skill.js"
 import { selectBuiltins, type BuiltinsConfig } from "./builtin.js"
 import { agentTools, parseAgentsConfig, type Agent } from "./a2a.js"
 import { startA2AServer, type A2AConfig, type OnTask, type ServeHandle } from "./serve.js"
+import { type MCPServeConfig, type OnCall } from "./mcpserve.js"
 import { toAnthropic, toGemini, toOpenAI } from "./adapters.js"
 import type { Client } from "./client.js"
 
@@ -31,6 +32,8 @@ export class Toolkit {
     extraTools: Tool[],
     /** A2A profile read from a top-level `a2a` config block (serve() falls back to this). */
     private readonly a2aConfig: A2AConfig | undefined,
+    /** MCP serve profile read from a top-level `mcpServer` config block. */
+    private readonly mcpServerConfig: MCPServeConfig | undefined,
   ) {
     // Builtins are the lowest-precedence source: a host extraTools entry with
     // the same name shadows a builtin (SPEC §4). Drop shadowed builtins up
@@ -87,7 +90,15 @@ export class Toolkit {
       a2aConfig = (opts.mcpConfig as { a2a?: A2AConfig }).a2a
     }
 
-    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig)
+    // MCP inbound profile: a top-level `mcpServer` (singular) block — distinct
+    // from the client-side `mcpServers` block. serve()/serveStdio() prefer their
+    // inline `mcp` over this.
+    let mcpServerConfig: MCPServeConfig | undefined
+    if (opts.mcpConfig && typeof opts.mcpConfig === "object" && "mcpServer" in opts.mcpConfig) {
+      mcpServerConfig = (opts.mcpConfig as { mcpServer?: MCPServeConfig }).mcpServer
+    }
+
+    return new Toolkit(mcp, skill, builtins, agentToolsFlat, opts.extraTools ?? [], a2aConfig, mcpServerConfig)
   }
 
   tools(): Tool[] {
@@ -129,8 +140,12 @@ export class Toolkit {
    * peer's turns are remembered through the client's ConversationStore.
    * When `a2a` is absent, no A2A routes are mounted. Returns a stoppable handle.
    */
-  serve(addr: string, opts: { client: Client; a2a?: A2AConfig; onTask?: OnTask }): Promise<ServeHandle> {
+  serve(
+    addr: string,
+    opts: { client?: Client; a2a?: A2AConfig; onTask?: OnTask; mcp?: MCPServeConfig; onCall?: OnCall },
+  ): Promise<ServeHandle> {
     const a2a = opts.a2a ?? this.a2aConfig
+    const mcp = opts.mcp ?? this.mcpServerConfig
     const skills = this.skill ? Object.values(this.skill.skills) : []
     return startA2AServer({
       addr,
@@ -138,9 +153,12 @@ export class Toolkit {
       skills,
       runTask: (text, contextId) =>
         contextId
-          ? opts.client.ask(text, { toolkit: this, id: contextId })
-          : opts.client.run(text, { toolkit: this }),
+          ? opts.client!.ask(text, { toolkit: this, id: contextId })
+          : opts.client!.run(text, { toolkit: this }),
       onTask: opts.onTask,
+      mcp,
+      mcpTools: mcp ? this.tools() : undefined,
+      onCall: opts.onCall,
     })
   }
 

package/src/types.ts

@@ -21,6 +21,50 @@ export interface ToolResult {
 export interface ToolContext {
   signal?: AbortSignal
   timeout?: number
+  /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
+  answer?: Answer
+}
+
+/**
+ * §10 Suspension. A tool that needs an out-of-band, async resolution (login, approval,
+ * input) returns a normal ToolResult carrying `metadata.pending = Request`. Byte-identical
+ * wire data — it crosses languages, processes, and agents unchanged.
+ */
+export interface Request {
+  id: string
+  kind: string // "authorization" | "approval" | "input" | ... (open vocabulary)
+  prompt: string
+  url?: string
+  data?: Record<string, unknown>
+  expiresAt?: string
+}
+
+export interface Answer {
+  id: string
+  ok: boolean
+  data?: Record<string, unknown>
+}
+
+let _pendingSeq = 0
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export function pending(request: Omit<Request, "id"> & { id?: string }): ToolResult {
+  const id = request.id ?? `pnd-${Date.now().toString(36)}-${++_pendingSeq}`
+  const req: Request = { ...request, id }
+  return {
+    output: req.prompt + (req.url ? `\n${req.url}` : ""),
+    isError: true,
+    metadata: { pending: req },
+  }
+}
+
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export function authRequired(url: string, prompt = "Authorization required to continue"): ToolResult {
+  return pending({ kind: "authorization", prompt, url })
+}
+
+/** Read the suspension off a result, if any. */
+export function pendingOf(result: ToolResult): Request | undefined {
+  return (result.metadata as { pending?: Request } | undefined)?.pending
 }
 
 export interface Tool {