> ## Documentation Index
> Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCPToolkit

> Expose tools from MCP servers to your agents.

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

```python theme={null}
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

<ParamField path="config" type="MCPConfig" required>
  MCP configuration with server definitions.
</ParamField>

<ParamField path="tool_name_prefix" type="str" default="&#x22;&#x22;">
  Prefix added to all tool names (e.g., `"mcp_"`).
</ParamField>

<ParamField path="include_server_prefix" type="bool" default="true">
  Whether to include the server name in tool names (e.g., `filesystem_list_files`).
</ParamField>

<ParamField path="require_confirmation" type="bool" default="false">
  Require user confirmation before executing any MCP tool.
</ParamField>

## Multiple Servers

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

```python theme={null}
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:

<CodeGroup>
  ```python Async (recommended) theme={null}
  async with MCPToolkit(config=config) as toolkit:
      agent = Agent(model=model, toolkits=[toolkit])
      output = await agent.arun("Do something")
  ```

  ```python Sync theme={null}
  with MCPToolkit(config=config) as toolkit:
      agent = Agent(model=model, toolkits=[toolkit])
      output = agent.run("Do something")
  ```
</CodeGroup>

Alternatively, manage the lifecycle manually:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
await toolkit.refresh_tools()
```

## Combining with Other Toolkits

MCP toolkit works alongside other toolkits and individual tools:

```python theme={null}
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:

```python theme={null}
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")
```

<Note>
  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.
</Note>

For more on MCP configuration, transports, and advanced features, see the [MCP section](/mcp/overview).