MCP and Delegation

MCPToolset

Import from @maniac-ai/agents/tools/adapters. One MCPToolset owns one MCP server connection:

import { MCPToolset } from "@maniac-ai/agents/tools/adapters";

const filesystem = new MCPToolset({
  name: "filesystem",
  description: "Local filesystem via MCP.",
  transport: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
});

const spec: Agent = {
  id: "assistant",
  instructions: "Use filesystem tools when needed.",
  model,
  toolsets: [filesystem]
};

Transports

Connection is lazy: the toolset opens on first listTools() / invoke() and stays open until aclose().

@modelcontextprotocol/sdk is an optional peer dependency — loaded only when a real transport opens.

Tool results

invoke prefers structuredContent from MCP responses, falling back to concatenated text content blocks.

Cancellation

Pass signal through tool invocation so aborting a run cancels in-flight MCP RPCs.

Delegated agents

BaseToolset.asDelegated() wraps a toolset as a single LM-facing tool that spawns a nested agent run:

import { OpenAICompatibleModel } from "@maniac-ai/agents/inference/adapters";

const delegated = filesystem.asDelegated({
  model: new OpenAICompatibleModel({ slug: "gpt-4o-mini" }),
  instructions: "You are a filesystem specialist. Be concise.",
  max_depth: 2
});

const spec: Agent = {
  id: "orchestrator",
  instructions: "Delegate filesystem work to the specialist tool.",
  model,
  tools: [delegated],
  max_depth: 2
};

The delegated tool exposes:

{
  "type": "object",
  "properties": { "prompt": { "type": "string" } },
  "required": ["prompt"]
}

Depth and policy

• max_depth on the parent spec caps nested delegation (default 1)
• When asDelegated({ policy }) omits policy, the nested run inherits the parent's effective policy
• Explicit policy: null opts out; a real policy is honoured as-is

Nested runs emit subagent trace events (start, completed, paused, errored) with depth, span_id, and parent_span_id for correlation.

delegated_tool expansion

Advanced toolsets can set delegated_tool: true with an extractSubActions callback to fan one LM tool call into multiple sub-invocations with per-sub approval — used for batched API operations.