MCPToolkit

The MCPToolkit connects to one or more MCP (Model Context Protocol) servers and exposes their tools as native agent tools. Your agent can call any tool from any connected MCP server without additional configuration.

Basic Usage

from definable.agent import Agent
from definable.mcp import MCPToolkit, MCPConfig, MCPServerConfig
from definable.model.openai import OpenAIChat

config = MCPConfig(servers=[
    MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    ),
])

toolkit = MCPToolkit(config=config)

async with toolkit:
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        toolkits=[toolkit],
    )
    output = await agent.arun("List the files in /tmp")
    print(output.content)

Parameters

MCPConfig

required

MCP configuration with server definitions.

str

default:"\"\""

Prefix added to all tool names (e.g., "mcp_").

bool

default:"true"

Whether to include the server name in tool names (e.g., filesystem_list_files).

bool

default:"false"

Require user confirmation before executing any MCP tool.

Multiple Servers

Connect to several MCP servers at once. Tools from all servers are available to the agent:

config = MCPConfig(servers=[
    MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    ),
    MCPServerConfig(
        name="github",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-github"],
    ),
])

toolkit = MCPToolkit(config=config)

Context Manager

MCPToolkit must be used as a context manager to properly manage server connections:

async with MCPToolkit(config=config) as toolkit:
    agent = Agent(model=model, toolkits=[toolkit])
    output = await agent.arun("Do something")

with MCPToolkit(config=config) as toolkit:
    agent = Agent(model=model, toolkits=[toolkit])
    output = agent.run("Do something")

Alternatively, manage the lifecycle manually:

toolkit = MCPToolkit(config=config)
await toolkit.initialize()

try:
    agent = Agent(model=model, toolkits=[toolkit])
    output = await agent.arun("Do something")
finally:
    await toolkit.shutdown()

Tool Discovery

After initialization, inspect available tools:

async with MCPToolkit(config=config) as toolkit:
    for t in toolkit.tools:
        print(f"{t.name}: {t.description}")

Refreshing Tools

If server tools change at runtime, refresh the tool list:

await toolkit.refresh_tools()

Combining with Other Toolkits

MCP toolkit works alongside other toolkits and individual tools:

agent = Agent(
    model=model,
    tools=[my_custom_tool],
    toolkits=[MCPToolkit(config=mcp_config), MathToolkit()],
)

Agent-Managed Lifecycle

Instead of manually managing the toolkit lifecycle with async with, you can let the agent handle it automatically. When you pass an uninitialized MCPToolkit to an agent, the agent will initialize it on first use and shut it down when the agent shuts down:

from definable.agent import Agent
from definable.mcp import MCPToolkit, MCPConfig, MCPServerConfig
from definable.model.openai import OpenAIChat

config = MCPConfig(servers=[
    MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    ),
])

# No `async with toolkit:` needed — agent handles lifecycle
toolkit = MCPToolkit(config=config)
agent = Agent(model=OpenAIChat(id="gpt-4o"), toolkits=[toolkit])
output = await agent.arun("List the files in /tmp")

# Or use the agent as a context manager for explicit cleanup
async with Agent(model=OpenAIChat(id="gpt-4o"), toolkits=[toolkit]) as agent:
    output = await agent.arun("List the files in /tmp")

If you pre-initialize the toolkit yourself (via async with toolkit: or await toolkit.initialize()), the agent detects this and does not take ownership — you remain responsible for shutting it down.

For more on MCP configuration, transports, and advanced features, see the MCP section.

Get Started

Basics

Capabilities

Advanced

Basic Usage

Parameters

Multiple Servers

Context Manager

Tool Discovery

Refreshing Tools

Combining with Other Toolkits

Agent-Managed Lifecycle

​Basic Usage

​Parameters

​Multiple Servers

​Context Manager

​Tool Discovery

​Refreshing Tools

​Combining with Other Toolkits

​Agent-Managed Lifecycle

Basic Usage

Parameters

Multiple Servers

Context Manager

Tool Discovery

Refreshing Tools

Combining with Other Toolkits

Agent-Managed Lifecycle