Model Context Protocol (MCP)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/harness/src/mcp-types.ts
• packages/harness/src/agent.ts
• packages/cea/src/agent.ts
• packages/harness/CHANGELOG.md
• packages/cea/CHANGELOG.md
• packages/minimal-agent/index.ts

The Model Context Protocol (MCP) integration within the project provides a standardized way to load and manage external tools for AI agents. It allows agents to connect to both local subprocess-based servers and remote HTTP/SSE services to discover and execute tools, effectively extending the agent's capabilities beyond its built-in toolset.

In this architecture, MCP serves as a bridge between the core agent loop and external service providers. The implementation supports automatic tool loading from configuration files (e.g., .mcp.json), reference-counted connection management, and merging tools from multiple sources while handling naming conflicts.

Sources: packages/harness/CHANGELOG.md:8-15, packages/harness/src/mcp-types.ts:1-5

Architecture and Tool Management

The MCP system is designed around a client-server model where the agent acts as the client. The MCPManager handles the lifecycle of these connections, including initialization, tool schema fetching, and cleanup.

Server Types

The protocol supports two primary transport mechanisms for MCP servers:

1. Stdio Servers: These are launched as local subprocesses. The configuration includes the executable command, optional arguments, and environment variables.
2. Remote Servers: These are accessed over the network via HTTP or Server-Sent Events (SSE).

The diagram shows how the MCP Manager aggregates tools from different server types into a single ToolSet for the Agent.
Sources: packages/harness/src/mcp-types.ts:11-35, packages/harness/CHANGELOG.md:12-14

Initialization Flow

When an agent is created via createAgent(), the mcp option triggers the initialization process. This process involves connecting to defined servers, listing available tools, and merging them into the agent's tool registry.

This sequence illustrates the tool discovery and merging process during agent startup.
Sources: packages/harness/CHANGELOG.md:8-11, packages/harness/src/mcp-types.ts:77-88

Configuration and Data Structures

MCP configuration can be provided inline during agent creation or loaded from a standardized configuration file.

MCP Configuration Formats

Parameter	Type	Description
command	string	The executable to run for stdio servers (e.g., "node", "python").
args	string[]	Optional arguments for the stdio command.
url	string	The base URL for remote HTTP/SSE servers.
type	"http" | "sse"	The transport type for remote servers.
env	Record<string, string>	Environment variables for stdio subprocesses.

Sources: packages/harness/src/mcp-types.ts:15-35

The .mcp.json File

The system can automatically look for a .mcp.json file in the project root. This file maps server names to their respective MCPServerConfig.

{
  "mcpServers": {
    "search-server": {
      "command": "npx",
      "args": ["-y", "duckduckgo-mcp@latest"]
    }
  }
}

Sources: packages/harness/src/mcp-types.ts:41-47, packages/minimal-agent/index.ts:123-128

Tool Merging and Conflict Resolution

Since multiple MCP servers can be connected simultaneously, the system implements a merging logic defined by MCPToolMergeResult.

• Merging: Tools from all connected servers are combined into a single ToolSet.
• Conflict Detection: If multiple servers provide a tool with the same name, the system identifies the conflict and records the sources.
• Timeouts: Fetching tool schemas from servers is subject to a configurable toolsTimeout (defaulting to 30,000ms) to prevent initialization hangs.

Sources: packages/harness/src/mcp-types.ts:77-96

Implementation in Agents

The protocol is integrated directly into the createAgent factory function.

• Lifecycle: The Agent class includes a close() method to ensure MCP connections are cleaned up properly when the agent is no longer needed.
• Reference Counting: The MCPManager uses reference counting to cache connections. If multiple agents share the same configuration, they reuse existing server connections.
• Minimal Agent Example: A practical implementation is seen in the minimal-agent, which utilizes a DuckDuckGo search MCP server via npx.

// Example of MCP configuration in agent creation
const agent = await createAgent({
  model,
  instructions: DEFAULT_SYSTEM_PROMPT,
  mcp: [
    {
      command: "npx",
      args: ["-y", "duckduckgo-mcp@latest"],
    },
  ],
});

Sources: packages/harness/CHANGELOG.md:10-15, packages/minimal-agent/index.ts:121-129, packages/cea/src/agent.ts:717-724

Summary

The Model Context Protocol (MCP) provides a robust framework for extending agent functionality through external tool servers. By supporting both local and remote transports, automated configuration loading, and efficient connection management, it enables the creation of highly capable and flexible AI agents within the plugsuits ecosystem. Integrated into the core createAgent flow, it abstracts the complexity of external tool orchestration from the developer.