MCP Configuration

MCPServerConfig

Each MCP server is defined with an MCPServerConfig:

from definable.mcp import MCPServerConfig

server = MCPServerConfig(
    name="my-server",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/home"],
    connect_timeout=30.0,
    request_timeout=60.0,
)

Connection Parameters

str

required

Unique identifier for this server. Used in tool name prefixes and logs.

str

default:"stdio"

Transport type: "stdio", "sse", or "http".

stdio Transport

str

Command to launch the server process (e.g., "npx", "python", "node").

List[str]

Command-line arguments for the server process.

SSE / HTTP Transport

str

Server URL for SSE or HTTP transports.

Dict[str, str]

Custom HTTP headers (e.g., authentication tokens).

Timeouts

float

default:"30.0"

Maximum time in seconds to establish the initial connection.

float

default:"60.0"

Maximum time in seconds for individual requests (tool calls, resource reads).

Reliability

bool

default:"true"

Automatically reconnect if the connection drops.

int

default:"3"

Maximum number of reconnection attempts.

Tool Filtering

List[str]

Whitelist of tool names. Only these tools will be exposed to the agent.

List[str]

Blacklist of tool names. These tools will be hidden from the agent.

# Only expose read operations
MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/data"],
    allowed_tools=["read_file", "list_directory", "search_files"],
)

# Block dangerous operations
MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/data"],
    blocked_tools=["write_file", "delete_file", "move_file"],
)

MCPConfig

Group multiple servers into a single configuration:

from definable.mcp import MCPConfig, MCPServerConfig

config = MCPConfig(
    servers=[
        MCPServerConfig(name="filesystem", transport="stdio", command="npx", args=["..."]),
        MCPServerConfig(name="github", transport="stdio", command="npx", args=["..."]),
        MCPServerConfig(name="api", transport="http", url="https://mcp.example.com"),
    ],
    auto_connect=True,
    reconnect_on_failure=True,
)

List[MCPServerConfig]

required

List of server configurations.

bool

default:"true"

Automatically connect to all servers on initialization.

bool

default:"true"

Global reconnection setting (can be overridden per server).

Loading from a File

Store configuration in a JSON file and load it:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "name": "api",
      "transport": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {"Authorization": "Bearer token"}
    }
  ]
}

config = MCPConfig.from_file("mcp_config.json")

Save configuration back to a file:

config.to_file("mcp_config.json")

Managing Servers

Add or remove servers dynamically:

config = MCPConfig(servers=[])

# Add a server
config.add_server(MCPServerConfig(name="fs", transport="stdio", command="npx", args=[...]))

# Get a specific server
server = config.get_server("fs")

# Remove a server
config.remove_server("fs")

Transport-Specific Examples

MCPServerConfig(
    name="sqlite",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-sqlite", "database.db"],
)

MCPServerConfig(
    name="remote-api",
    transport="sse",
    url="https://mcp.example.com/sse",
    headers={"Authorization": "Bearer sk-..."},
    connect_timeout=10.0,
)

MCPServerConfig(
    name="modern-api",
    transport="http",
    url="https://mcp.example.com/mcp",
    headers={"Authorization": "Bearer sk-..."},
    request_timeout=120.0,
)

Get Started

Basics

Capabilities

Advanced

MCPServerConfig

Connection Parameters

stdio Transport

SSE / HTTP Transport

Timeouts

Reliability

Tool Filtering

MCPConfig

Loading from a File

Managing Servers

Transport-Specific Examples

​MCPServerConfig

​Connection Parameters

​stdio Transport

​SSE / HTTP Transport

​Timeouts

​Reliability

​Tool Filtering

​MCPConfig

​Loading from a File

​Managing Servers

​Transport-Specific Examples

MCPServerConfig

Connection Parameters

stdio Transport

SSE / HTTP Transport

Timeouts

Reliability

Tool Filtering

MCPConfig

Loading from a File

Managing Servers

Transport-Specific Examples