MCP Protocol Architecture

Tier 2 | Deep technical documentation for MCP server development Hub: README.md | Full Architecture: ARCHITECTURE.md

Overview

Model Context Protocol (MCP) integration enables Claude Desktop to orchestrate nexus-agents. The system implements the MCP 2025-11-25 specification.

Key Capabilities

• Tool Definitions - Zod-validated tool schemas
• Structured Output - JSON and text content blocks
• Resource Management - Dynamic context exposure
• Error Handling - Tool errors vs protocol errors

MCP Server Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Claude Desktop                            │
│                         │                                    │
│                    MCP Protocol                              │
│                         │                                    │
└─────────────────────────┼───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                  MCP Server (nexus-agents)                   │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                    Tool Registry                        │ │
│  │  orchestrate │ delegate │ expert │ workflow │ ...      │ │
│  └──────────────────────────┬─────────────────────────────┘ │
│                             │                                │
│  ┌──────────────────────────▼─────────────────────────────┐ │
│  │              Validation Layer (Zod)                     │ │
│  └──────────────────────────┬─────────────────────────────┘ │
│                             │                                │
│  ┌──────────────────────────▼─────────────────────────────┐ │
│  │              Agent Orchestration                        │ │
│  │  Orchestrator │ Expert Pool │ Consensus │ Workflows    │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Tool Design Pattern

server.tool(
  'tool_name',
  {
    // Zod schema with descriptions (Claude uses these)
    param: z.string().describe('What this parameter does'),
    optional: z.number().optional().describe('Optional parameter'),
  },
  async (args) => {
    // 1. Validate input (already done by SDK, but double-check business rules)
    const validated = Schema.safeParse(args);
    if (!validated.success) {
      return {
        isError: true,
        content: [{ type: 'text', text: validated.error.message }],
      };
    }

    // 2. Execute with proper error handling
    try {
      const result = await doWork(validated.data);
      return {
        content: [{ type: 'text', text: JSON.stringify(result) }],
      };
    } catch (error) {
      return {
        isError: true,
        content: [{ type: 'text', text: error.message }],
      };
    }
  }
);

Tool Design Rules

1. Clear names - Verb-noun format: create_expert, run_workflow
2. Detailed descriptions - Claude uses these to decide when to call
3. Zod validation - All inputs validated at tool boundary
4. Tool errors vs protocol errors - Use isError: true for tool failures
5. Structured output - Support both structuredContent and TextContent

Tool Interface

interface ITool {
  readonly name: string;
  readonly description: string;
  readonly inputSchema: z.ZodSchema;

  execute(input: unknown): Promise<ToolResult>;
}

interface IToolRegistry {
  register(tool: ITool): void;
  get(name: string): ITool | undefined;
  list(): ToolInfo[];
  unregister(name: string): boolean;
}

interface ToolResult {
  isError?: boolean;
  content: ToolContentBlock[];
}

type ToolContentBlock =
  | { type: 'text'; text: string }
  | { type: 'image'; data: string; mimeType: string }
  | { type: 'resource'; uri: string; mimeType?: string };

Registered Tools

Tool Examples

orchestrate

// Input
{ task: "Review this code for security issues", context: { file: "auth.ts" } }

// Output
{ summary: "...", experts_consulted: ["security", "code"], recommendations: [...] }

workflow

// Input
{ template: "code-review", inputs: { url: "https://github.com/..." }, dryRun: false }

// Output
{ status: "completed", steps: [...], output: "..." }

Tool Annotation Taxonomy (MCP 2025-11-25)

Every registered MCP tool declares all four annotation hints from the 2025-11-25 spec. Annotations live in a single source of truth — packages/nexus-agents/src/mcp/tool-annotations.ts — and each server.registerTool() call reads its annotations via getToolAnnotations(name). CI gate check:tool-annotations enforces parity between the central map and the registered tools.

Per the MCP spec these are hints, not enforcement primitives — clients should never make safety decisions based on annotations received from untrusted servers. nexus-agents uses them for: programmatic prerequisite gates (#2652), retry-policy decisions in pipeline runners (only retry tools where idempotentHint === true), and permission-prompt UX consistency across harnesses.

Why no tool is destructiveHint: true

A destructiveHint: true tool can delete or overwrite data without the caller’s input. nexus-agents tools are universally additive (writes are creates, not deletes) or return-only — no tool’s body calls rm, DELETE FROM, or equivalent. If a future tool needs destructiveHint: true (e.g., a “drop registry entry” tool), it should also wire a prerequisite gate per #2652.

Adding a new tool

1. Implement the tool in packages/nexus-agents/src/mcp/tools/<tool>.ts.
2. Add it to REGISTERED_TOOL_NAMES in packages/nexus-agents/src/mcp/tools/index.ts.
3. Add its annotations to TOOL_ANNOTATIONS in packages/nexus-agents/src/mcp/tool-annotations.ts.
4. Pass annotations: getToolAnnotations('your_tool_name') to the server.registerTool() config object.
5. Run npx tsx scripts/inject-governance.ts check — check:tool-annotations confirms parity.

Resource Exposure

Dynamic context exposure to Claude:

server.resource('project_context', 'text/markdown', async () => {
  const content = await readFile('CLAUDE.md', 'utf-8');
  return { content };
});

// Claude can read with:
// resource://nexus-agents/project_context

Resource Types

Testing MCP Tools

import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

describe('MCP Tools', () => {
  let client: Client;
  let server: Server;

  beforeEach(async () => {
    // Create linked transport pair
    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

    server = createServer();
    client = new Client({ name: 'test-client' });

    await server.connect(serverTransport);
    await client.connect(clientTransport);
  });

  it('should orchestrate task', async () => {
    const result = await client.callTool({
      name: 'orchestrate',
      arguments: { task: 'Test task' },
    });

    expect(result.isError).toBe(false);
    expect(result.content).toHaveLength(1);
  });
});

Error Handling

Tool Errors (Recoverable)

Use for expected failures:

return {
  isError: true,
  content: [
    {
      type: 'text',
      text: 'Validation failed: task cannot be empty',
    },
  ],
};

Protocol Errors (Unexpected)

Throw for unexpected failures:

throw new McpError(ErrorCode.InternalError, 'Database connection failed');

Error Categories

Extension: Adding a New Tool

1. Define Tool Interface

// src/mcp/tools/my-tool.ts
import { z } from 'zod';
import { ITool, ToolResult } from '../types.js';

const InputSchema = z.object({
  param: z.string().describe('What this does'),
  option: z.number().optional().describe('Optional setting'),
});

export const myTool: ITool = {
  name: 'my_tool',
  description: 'Does something useful',
  inputSchema: InputSchema,

  async execute(input: unknown): Promise<ToolResult> {
    const args = InputSchema.parse(input);
    // ... implementation
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }],
    };
  },
};

2. Register with Server

// src/mcp/index.ts
import { myTool } from './tools/my-tool.js';

export function registerTools(server: McpServer, registry: IToolRegistry): void {
  registry.register(myTool);
  // ... other tools
}

3. Add Tests

// src/mcp/tools/my-tool.test.ts
describe('my_tool', () => {
  it('should handle valid input', async () => {
    const result = await myTool.execute({ param: 'test' });
    expect(result.isError).toBeFalsy();
  });

  it('should reject invalid input', async () => {
    await expect(myTool.execute({})).rejects.toThrow();
  });
});

Configuration

mcp:
  server:
    name: nexus-agents
    version: 2.2.0
    capabilities:
      tools: true
      resources: true
      prompts: true # 4 prompts registered

  transport: stdio # stdio | tcp
  # tcp:
  #   port: 3000
  #   host: localhost

  tools:
    orchestrate:
      maxTurns: 10
      timeout: 300000 # 5 minutes
    workflow:
      dryRunDefault: false

Client Request Timeouts — Long-Running Tools

The MCP TypeScript SDK ships with DEFAULT_REQUEST_TIMEOUT_MSEC = 60_000 (see @modelcontextprotocol/sdk → shared/protocol.ts). That is a client-side cap on how long the client will wait for a tool response. If a nexus-agents tool has a configured per-tool budget that exceeds this, the client will kill the request before the server-side deadline can fire.

Long-running tools (orchestrate, consensus_vote, run_workflow) have multi-minute budgets configured in MCP_TIMEOUTS.perTool (packages/nexus-agents/src/config/timeouts.ts). Callers MUST configure their client to:

1. Pass options.onprogress in the SDK client.request() call. The SDK only injects _meta.progressToken into the JSON-RPC payload when an onprogress handler is supplied (shared/protocol.ts:643). Without progressToken, the server’s withProgressHeartbeat emits notifications into a void.

2. Set options.resetTimeoutOnProgress: true. The SDK only resets the per-request timer when an notifications/progress arrives AND this flag is true (shared/protocol.ts:714). Default is false.

3. OR raise options.timeout explicitly to the tool’s worst-case budget (e.g. 600_000 for consensus_vote, 900_000 for orchestrate). Sufficient if you don’t want streaming progress, but the request will block for that long.

// Example: invoking consensus_vote from a custom MCP client
const result = await client.request(
  { method: 'tools/call', params: { name: 'consensus_vote', arguments: { ... } } },
  CallToolResultSchema,
  {
    timeout: 600_000,
    resetTimeoutOnProgress: true,
    onprogress: (notif) => console.log(`heartbeat #${notif.progress}`),
  }
);

Operator diagnostic

toSdkCallbackWithBudgetCheck (packages/nexus-agents/src/mcp/middleware/tool-wrapper.ts) emits a WARN at invocation time when a tool’s configured budget exceeds the SDK default AND the request arrived without _meta.progressToken. The WARN names the tool, the configured budget, and the SDK default — operators can grep server logs to confirm whether a “tool timed out” failure is actually a client-config mismatch rather than a real CLI failure. (Source: audit on #2619 / #2631.)

[warn] MCP tool budget exceeds client default and no progressToken received — request likely to be killed by client before server-side deadline
  tool=consensus_vote configuredTimeoutMs=600000 mcpSdkDefaultMs=60000

If you see this WARN on every long-running tool call, the client is misconfigured — fix the client, not the server timeout.

Correlation-keyed event log (#2703)

The WARN above is also recorded as one JSONL row per mismatch at $NEXUS_DATA_DIR/mcp-telemetry/timeout-mismatch-events.jsonl. Each row carries a correlation eventId that also appears in the WARN log entry’s context, so a mismatched call can be joined from server logs to the recorded outcome — not just counted in aggregate.

Schema (one JSON object per line):

This is the data surface for Epic #2631’s “when this is worth doing” gate: “of mismatches, what fraction end in errorCategory: 'timeout'?” The aggregation belongs in improvement_review / a fitness report (out of scope for #2703).

Claude Desktop Integration

Setup

Add to .mcp.json in your project root (or use claude mcp add-json):

{
  "mcpServers": {
    "nexus-agents": {
      "command": "nexus-agents",
      "args": ["--mode=server"]
    }
  }
}

Verification

# Test MCP server starts correctly
nexus-agents --mode=server --verbose

# Check tool registration
# Look for: "Registered tool: orchestrate"

Source Files

Protocol Reference

• Specification: modelcontextprotocol.io
• SDK Version: @modelcontextprotocol/sdk@1.27.1
• Protocol Version: 2025-11-25

Related Documents

• Agent System: AGENT_SYSTEM.md
• Security: SECURITY.md
• Full Architecture: ARCHITECTURE.md
• API Reference: ENTRYPOINTS.md