mcp.config¶

MCP configuration types for flexible server management.

This module provides Pydantic models for configuring Model Context Protocol (MCP) servers and their integration with Haive agents. It includes comprehensive validation and type safety for all MCP-related configurations.

The configuration system supports:

Multiple transport types (stdio, SSE, HTTP streaming)
Server-specific settings and capabilities
Environment variables and authentication
Discovery and filtering options
Health monitoring and retry logic

Classes:

MCPTransport: Enumeration of supported MCP transport types MCPServerConfig: Configuration for individual MCP servers MCPConfig: Complete MCP configuration for agents

Examples

Creating an MCP server configuration:

from haive.mcp.config import MCPConfig, MCPServerConfig, MCPTransport

# Configure a filesystem MCP server
fs_server = MCPServerConfig(
    name="filesystem",
    transport=MCPTransport.STDIO,
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem"],
    capabilities=["file_read", "file_write", "directory_list"],
    category="filesystem",
    description="Local filesystem operations"
)

# Create complete MCP config
config = MCPConfig(
    enabled=True,
    servers={"filesystem": fs_server},
    auto_discover=True,
    lazy_init=True
)

Note

All configuration models use Pydantic v2 for validation and serialization.

Classes¶

`MCPConfig`	Complete MCP configuration for an agent.
`MCPServerConfig`	Configuration for a single MCP server.
`MCPTransport`	MCP transport types.

Module Contents¶

class mcp.config.MCPConfig(/, **data: Any)¶

Bases: pydantic.BaseModel

Complete MCP configuration for an agent.

This class provides the main configuration structure for MCP integration with Haive agents. It controls server discovery, filtering, initialization, and runtime behavior.

enabled¶: Whether MCP functionality is enabled

auto_discover¶: Automatically discover servers from configured paths

lazy_init¶: Initialize servers on-demand rather than at startup

servers¶: Dictionary mapping server names to their configurations

discovery_paths¶: List of paths to search for MCP server configurations

categories¶: Optional filter for server categories

required_capabilities¶: Optional list of required server capabilities

global_timeout¶: Timeout for all MCP operations in seconds

max_concurrent_servers¶: Maximum number of concurrent server connections

enable_health_checks¶: Whether to enable periodic server health checks

on_server_connected¶: Optional callback name when server connects

on_server_failed¶: Optional callback name when server fails

on_tool_discovered¶: Optional callback name when tool is discovered

Examples

Creating a comprehensive MCP configuration:

config = MCPConfig(
    enabled=True,
    servers={
        "filesystem": MCPServerConfig(...),
        "github": MCPServerConfig(...),
    },
    categories=["development", "filesystem"],
    required_capabilities=["file_read"],
    global_timeout=120,
    max_concurrent_servers=5
)

auto_discover: bool = None¶

categories: list[str] | None = None¶

discovery_paths: list[str] = None¶

enable_health_checks: bool = None¶

enabled: bool = None¶

global_timeout: int = None¶

lazy_init: bool = None¶

max_concurrent_servers: int = None¶

on_server_connected: str | None = None¶

on_server_failed: str | None = None¶

on_tool_discovered: str | None = None¶

required_capabilities: list[str] | None = None¶

servers: dict[str, MCPServerConfig] = None¶

class mcp.config.MCPServerConfig(/, **data: Any)¶

Bases: pydantic.BaseModel

Configuration for a single MCP server.

Represents the complete configuration needed to connect to and use an MCP server. Supports multiple transport types and provides extensive customization options.

name¶: Unique identifier for the server

enabled¶: Whether this server should be activated

transport¶: Communication transport type (stdio, sse, streamable_http)

command¶: Executable command for stdio transport

args¶: Command arguments for stdio transport

url¶: Server URL for HTTP-based transports

env¶: Environment variables to set when starting server

api_key¶: Optional API key for authentication

category¶: Server category for organization (e.g., “filesystem”, “database”)

description¶: Human-readable description of server functionality

capabilities¶: List of capabilities provided by the server

timeout¶: Connection timeout in seconds

retry_attempts¶: Number of retry attempts on connection failure

auto_start¶: Whether to automatically start the server

health_check_interval¶: Interval for health checks in seconds

Examples

Creating a GitHub MCP server config:

config = MCPServerConfig(
    name="github",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
    env={"GITHUB_TOKEN": "your_token"},
    capabilities=["repo_access", "issue_management"],
    category="development",
    description="GitHub repository operations"
)

api_key: str | None = None¶

args: list[str] | None = None¶

auto_start: bool = None¶

capabilities: list[str] = None¶

category: str | None = None¶

command: str | None = None¶

description: str | None = None¶

enabled: bool = None¶

env: dict[str, str] = None¶

health_check_interval: int | None = None¶

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str = None¶

retry_attempts: int = None¶

timeout: int = None¶

transport: MCPTransport = None¶

url: str | None = None¶

class mcp.config.MCPTransport¶

Bases: str, enum.Enum

MCP transport types.

Defines the communication transport mechanisms supported by MCP servers.

STDIO¶: Standard input/output communication (default for CLI-based servers)

SSE¶: Server-Sent Events for HTTP-based streaming

STREAMABLE_HTTP¶: HTTP streaming for continuous data transfer

SSE = 'sse'¶

STDIO = 'stdio'¶

STREAMABLE_HTTP = 'streamable_http'¶