MCP Servers

Agentix supports the Model Context Protocol (MCP) for extending the agent with external tool servers.

Configuration styles

MCP servers are configured as a dict in mcp_servers. The key is the server name; the value is a config dict or object.

stdio server

options = AgentixAgentOptions(
    mcp_servers={
        "filesystem": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        }
    }
)

SSE server

options = AgentixAgentOptions(
    mcp_servers={
        "remote-tools": {
            "type": "sse",
            "url": "https://my-mcp-server.example.com/sse",
            "headers": {"Authorization": "Bearer my-token"},
        }
    }
)

HTTP server

options = AgentixAgentOptions(
    mcp_servers={
        "remote-tools": {
            "type": "http",
            "url": "https://my-mcp-server.example.com/mcp",
        }
    }
)

JSON-RPC server

from agentix import McpJsonRpcServerConfig

options = AgentixAgentOptions(
    mcp_servers={
        "jsonrpc-tools": {
            "type": "jsonrpc",
            "url": "https://my-server.example.com/jsonrpc",
        }
    }
)
# McpJsonRpcServerConfig is available as a typed dataclass for IDE/type-checker support:
# from agentix import McpJsonRpcServerConfig

In-process SDK server

Create an in-process MCP server using the @mcp_tool decorator and create_sdk_mcp_server:

from agentix import AgentixAgentOptions, create_sdk_mcp_server, mcp_tool

@mcp_tool(name="get_stock_price", description="Get the current stock price for a ticker symbol.")
async def get_stock_price(args: dict) -> dict:
    symbol = args.get("symbol", "")
    # ... fetch price ...
    price = 42.00
    return {"content": [{"type": "text", "text": f"${price}"}]}

options = AgentixAgentOptions(
    name="finance-agent",
    mcp_servers={
        "finance": create_sdk_mcp_server("finance", "1.0", [get_stock_price])
    }
)

MCP tool names and allowed_tools

Every tool exposed by an MCP server is registered under the name mcp__<server-name>__<tool-name>. For example, a server named "agentix-docs" that exposes a search_docs tool registers it as mcp__agentix-docs__search_docs.

By default (allowed_tools=[]), all tools — built-in and MCP — are available to the agent with no extra configuration needed:

options = AgentixAgentOptions(
    mcp_servers={
        "agentix-docs": {"type": "http", "url": "https://example.com/mcp"}
    }
    # allowed_tools omitted — agent can use all built-in and MCP tools freely
)

If you want to block specific tools while keeping MCP tools open, use disallowed_tools:

options = AgentixAgentOptions(
    mcp_servers={
        "agentix-docs": {"type": "http", "url": "https://example.com/mcp"}
    },
    disallowed_tools=["Bash", "Write"],  # block dangerous built-ins; MCP tools remain available
)

Wildcard patterns for MCP tools

allowed_tools and disallowed_tools support fnmatch-style wildcard patterns for any entry whose prefix is mcp__. This lets you allow or block an entire MCP server without knowing its tool list in advance — which is useful because MCP tool names are only discovered at connection time.

options = AgentixAgentOptions(
    mcp_servers={
        "agentix-docs": {"type": "http", "url": "https://example.com/mcp"}
    },
    allowed_tools=[
        "Read", "Glob", "Grep",       # exact built-in names
        "mcp__agentix-docs__*",       # all tools from the agentix-docs server
    ],
)

Common wildcard patterns:

Pattern	Matches
"mcp__agentix-docs__*"	Every tool from the agentix-docs server
"mcp__*"	Every tool from every MCP server
"mcp__agentix-docs__search_*"	Only tools whose name starts with search_

Built-in tools are always exact-matched. Wildcards are only expanded for patterns that start with mcp__. A pattern like "Bas*" or "*" is treated as a literal string and will not match Bash or any other built-in.

Only use allowed_tools when you genuinely want to lock the agent to a fixed, known set of tools. For broad access to an MCP server alongside specific built-ins, combine exact names with a wildcard:

allowed_tools=[
    "Read", "Glob",                  # specific built-ins only
    "mcp__agentix-docs__*",          # all tools from one server
    "mcp__internal-api__get_*",      # only read-like tools from another
]

---

Checking MCP server status

statuses = client.get_mcp_status()
for status in statuses:
    print(status.name, status.status)   # status.status: "connected" | "error" | "timeout"
    print(status.tools)                 # list[str] of registered tool names
    if status.error:
        print(status.error)

Connection timeout

options = AgentixAgentOptions(
    mcp_connect_timeout=60.0,  # default: 60s; override via AGENTIX_MCP_CONNECT_TIMEOUT
)