Configuration¶

The haive-mcp package provides flexible configuration options for MCP servers, discovery, and agent integration.

Configuration Classes¶

MCPTransport¶

class haive.mcp.config.MCPTransport(*values)[source]¶

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'¶

Supported transport types:

stdio: Standard input/output communication (most common)
sse: Server-Sent Events for HTTP streaming
streamable_http: HTTP streaming for continuous data transfer

MCPServerConfig¶

class haive.mcp.config.MCPServerConfig(*, name: str, enabled: bool = True, transport: ~haive.mcp.config.MCPTransport = MCPTransport.STDIO, command: str | None = None, args: list[str] | None = <factory>, url: str | None = None, env: dict[str, str] = <factory>, api_key: str | None = None, category: str | None = None, description: str | None = None, capabilities: list[str] = <factory>, timeout: int = 30, retry_attempts: int = 3, auto_start: bool = True, health_check_interval: int | None = None, **extra_data: ~typing.Any)[source]¶

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

Type:: str

enabled¶

Whether this server should be activated

Type:: bool

transport¶

Communication transport type (stdio, sse, streamable_http)

Type:: haive.mcp.config.MCPTransport

command¶

Executable command for stdio transport

Type:: str | None

args¶

Command arguments for stdio transport

Type:: list[str] | None

url¶

Server URL for HTTP-based transports

Type:: str | None

env¶

Environment variables to set when starting server

Type:: dict[str, str]

api_key¶

Optional API key for authentication

Type:: str | None

category¶

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

Type:: str | None

description¶

Human-readable description of server functionality

Type:: str | None

capabilities¶

List of capabilities provided by the server

Type:: list[str]

timeout¶

Connection timeout in seconds

Type:: int

retry_attempts¶

Number of retry attempts on connection failure

Type:: int

auto_start¶

Whether to automatically start the server

Type:: bool

health_check_interval¶

Interval for health checks in seconds

Type:: int | None

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¶

args: list[str] | None¶

auto_start: bool¶

capabilities: list[str]¶

category: str | None¶

command: str | None¶

description: str | None¶

enabled: bool¶

env: dict[str, str]¶

health_check_interval: int | None¶

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str¶

retry_attempts: int¶

timeout: int¶

transport: MCPTransport¶

url: str | None¶

Key configuration fields:

MCPServerConfig(
    name="server_name",           # Unique identifier
    enabled=True,                 # Whether to activate
    transport="stdio",            # Communication method
    command="npx",                # Executable command
    args=["-y", "package-name"],  # Command arguments
    url="http://localhost:3000",  # For HTTP transports
    env={"KEY": "value"},         # Environment variables
    api_key="secret",             # Authentication key
    category="filesystem",        # Organizational category
    description="Server purpose", # Human-readable description
    capabilities=["read", "write"], # Server capabilities
    timeout=30,                   # Connection timeout (seconds)
    retry_attempts=3,             # Retry count on failure
    auto_start=True,              # Auto-start on init
    health_check_interval=60      # Health check frequency
)

MCPConfig¶

class haive.mcp.config.MCPConfig(*, enabled: bool = False, auto_discover: bool = True, lazy_init: bool = True, servers: dict[str, ~haive.mcp.config.MCPServerConfig] = <factory>, discovery_paths: list[str] = <factory>, categories: list[str] | None = None, required_capabilities: list[str] | None = None, global_timeout: int = 60, max_concurrent_servers: int = 10, enable_health_checks: bool = True, on_server_connected: str | None = None, on_server_failed: str | None = None, on_tool_discovered: str | None = None)[source]¶

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

Type:: bool

auto_discover¶

Automatically discover servers from configured paths

Type:: bool

lazy_init¶

Initialize servers on-demand rather than at startup

Type:: bool

servers¶

Dictionary mapping server names to their configurations

Type:: dict[str, haive.mcp.config.MCPServerConfig]

discovery_paths¶

List of paths to search for MCP server configurations

Type:: list[str]

categories¶

Optional filter for server categories

Type:: list[str] | None

required_capabilities¶

Optional list of required server capabilities

Type:: list[str] | None

global_timeout¶

Timeout for all MCP operations in seconds

Type:: int

max_concurrent_servers¶

Maximum number of concurrent server connections

Type:: int

enable_health_checks¶

Whether to enable periodic server health checks

Type:: bool

on_server_connected¶

Optional callback name when server connects

Type:: str | None

on_server_failed¶

Optional callback name when server fails

Type:: str | None

on_tool_discovered¶

Optional callback name when tool is discovered

Type:: str | None

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¶

categories: list[str] | None¶

discovery_paths: list[str]¶

enable_health_checks: bool¶

enabled: bool¶

global_timeout: int¶

lazy_init: bool¶

max_concurrent_servers: int¶

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

on_server_connected: str | None¶

on_server_failed: str | None¶

on_tool_discovered: str | None¶

required_capabilities: list[str] | None¶

servers: dict[str, MCPServerConfig]¶

Main configuration options:

MCPConfig(
    enabled=True,                 # Enable MCP functionality
    auto_discover=True,           # Auto-discover servers
    lazy_init=False,              # Initialize immediately
    servers={},                   # Server configurations
    discovery_paths=[],           # Paths to search for configs
    categories=["dev", "data"],   # Filter by categories
    required_capabilities=[],     # Required server capabilities
    global_timeout=60,            # Global operation timeout
    max_concurrent_servers=10,    # Max concurrent connections
    enable_health_checks=True,    # Enable health monitoring
    on_server_connected="callback", # Connection callback
    on_server_failed="callback",   # Failure callback
    on_tool_discovered="callback"  # Tool discovery callback
)

Configuration Examples¶

Basic Filesystem Server¶

from haive.mcp.config import MCPConfig, MCPServerConfig

config = MCPConfig(
    enabled=True,
    servers={
        "filesystem": MCPServerConfig(
            name="filesystem",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem"],
            env={"ALLOWED_PATHS": "/home/user/documents"},
            capabilities=["file_read", "file_write", "directory_list"],
            timeout=30
        )
    }
)

Multi-Server Development Environment¶

config = MCPConfig(
    enabled=True,
    servers={
        "filesystem": MCPServerConfig(
            name="filesystem",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem"],
            category="storage"
        ),
        "github": MCPServerConfig(
            name="github",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-github"],
            env={"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")},
            category="development"
        ),
        "postgres": MCPServerConfig(
            name="postgres",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-postgres"],
            env={"DATABASE_URL": "postgresql://localhost/dev"},
            category="database"
        )
    },
    categories=["development", "database"],  # Only load these categories
    required_capabilities=["database_query"], # Must have DB access
    max_concurrent_servers=5,
    enable_health_checks=True
)

HTTP-Based Server¶

config = MCPConfig(
    enabled=True,
    servers={
        "api_server": MCPServerConfig(
            name="api_server",
            transport="sse",  # Server-Sent Events
            url="http://localhost:3000/mcp",
            api_key="your-api-key",
            timeout=60,
            health_check_interval=30
        )
    }
)

Custom Server Configuration¶

config = MCPConfig(
    enabled=True,
    servers={
        "custom_server": MCPServerConfig(
            name="custom_server",
            transport="stdio",
            command="python",
            args=["/path/to/my_server.py", "--port", "8080"],
            env={
                "SERVER_MODE": "production",
                "LOG_LEVEL": "INFO",
                "API_KEY": os.getenv("CUSTOM_API_KEY")
            },
            capabilities=["custom_tool", "data_analysis"],
            category="custom",
            description="My custom MCP server implementation",
            timeout=45,
            retry_attempts=5,
            health_check_interval=120
        )
    }
)

Discovery Configuration¶

Automatic Server Discovery¶

config = MCPConfig(
    enabled=True,
    auto_discover=True,
    discovery_paths=[
        "~/.mcp/servers",      # User config directory
        ".mcp/servers",        # Project-local configs
        "mcp_servers",         # Custom directory
        "/etc/mcp/servers"     # System-wide configs
    ],
    categories=["filesystem", "development"],  # Filter discovered servers
    required_capabilities=["file_read"]        # Capability requirements
)

Manual Server Configuration¶

config = MCPConfig(
    enabled=True,
    auto_discover=False,  # Disable auto-discovery
    servers={
        # Explicitly configured servers only
        "filesystem": MCPServerConfig(...),
        "github": MCPServerConfig(...)
    }
)

Environment Variables¶

You can also configure MCP servers using environment variables:

# Enable MCP
export MCP_ENABLED=true

# Set global timeout
export MCP_GLOBAL_TIMEOUT=120

# Configure filesystem server
export MCP_FILESYSTEM_ENABLED=true
export MCP_FILESYSTEM_COMMAND=npx
export MCP_FILESYSTEM_ARGS="-y,@modelcontextprotocol/server-filesystem"
export MCP_FILESYSTEM_ALLOWED_PATHS="/home/user"

# Configure GitHub server
export MCP_GITHUB_ENABLED=true
export MCP_GITHUB_TOKEN="your_github_token"

Configuration Files¶

JSON Configuration¶

Create a mcp_config.json file:

{
    "enabled": true,
    "auto_discover": true,
    "servers": {
        "filesystem": {
            "name": "filesystem",
            "transport": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem"],
            "capabilities": ["file_read", "file_write"],
            "timeout": 30
        },
        "github": {
            "name": "github",
            "transport": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"},
            "capabilities": ["repo_access"]
        }
    }
}

YAML Configuration¶

Create a mcp_config.yaml file:

enabled: true
auto_discover: true
global_timeout: 60
max_concurrent_servers: 10

servers:
  filesystem:
    name: filesystem
    transport: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
    env:
      ALLOWED_PATHS: "/home/user/documents"
    capabilities:
      - file_read
      - file_write
      - directory_list
    timeout: 30

  github:
    name: github
    transport: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    capabilities:
      - repo_access
      - issue_management

Loading Configurations¶

import json
import yaml
from haive.mcp.config import MCPConfig

# From JSON
with open("mcp_config.json") as f:
    config_data = json.load(f)
config = MCPConfig(**config_data)

# From YAML
with open("mcp_config.yaml") as f:
    config_data = yaml.safe_load(f)
config = MCPConfig(**config_data)

# From environment (using a helper function)
config = MCPConfig.from_env()

Best Practices¶

Use categories to organize servers by purpose
Set appropriate timeouts based on server complexity
Enable health checks for production environments
Use environment variables for sensitive data like API keys
Start with lazy_init=True for faster startup times
Monitor server health and implement failure callbacks
Test configurations in development before production deployment