# How to Convert MCP Config Dicts to Callable Tools in aisuite

> Learn how to convert MCP config dicts to callable tools in aisuite using a validation-client-wrapper pipeline. Easily integrate with the aisuite chat completion API.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-06-15

---

**aisuite converts MCP configuration dictionaries into callable Python tools through a validation-client-wrapper pipeline that enables direct integration with the aisuite chat completion API.**

The aisuite library provides native support for the Model Context Protocol (MCP), allowing you to convert MCP configuration dictionaries into executable Python functions. This conversion bridges external MCP servers—whether running via stdio or HTTP—with aisuite's unified chat completion interface. Understanding this pipeline helps you integrate external tool providers without writing custom integration code.

## Understanding the MCP Config-to-Tool Pipeline

The conversion from configuration dictionary to callable tool follows a four-stage pipeline implemented across aisuite's MCP modules.

### Step 1: Validate the MCP Configuration

The process begins with `aisuite.mcp.config.validate_mcp_config`, which inspects the dictionary for required fields, detects the transport mechanism (stdio versus HTTP), and applies default values for `timeout_seconds` and `use_tool_prefix`. This validation occurs in [`aisuite/mcp/config.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/config.py) (lines 49-112) and ensures the configuration is ready for client instantiation.

### Step 2: Create the MCPClient

The `MCPClient.from_config` method receives the validated configuration and determines the appropriate transport via `get_transport_type` (lines 44-58 in [`config.py`](https://github.com/andrewyng/aisuite/blob/main/config.py)). The client then establishes the connection—whether spawning a subprocess for stdio or opening an HTTP session—and discovers the available tools from the MCP server (lines 33-75 in [`aisuite/mcp/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/client.py)).

### Step 3: Wrap MCP Tools as Python Callables

For each tool returned by `list_tools()`, the `MCPClient.get_callable_tools` method constructs a wrapper using `create_mcp_tool_wrapper` (lines 75-93 in [`client.py`](https://github.com/andrewyng/aisuite/blob/main/client.py)). The `MCPToolWrapper` class stores the tool name, description, and schema, then performs three critical transformations:

- **Type Annotation Conversion**: The `mcp_schema_to_annotations` function in [`aisuite/mcp/schema_converter.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/schema_converter.py) (lines 60-104) converts JSON Schema definitions into Python type hints.
- **Signature Generation**: The `_create_signature` method in [`aisuite/mcp/tool_wrapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/tool_wrapper.py) (lines 77-107) builds a proper `inspect.Signature` object, enabling aisuite's `Tools` class to introspect parameters.
- **Docstring Construction**: The `build_docstring` function (lines 78-98 in [`schema_converter.py`](https://github.com/andrewyng/aisuite/blob/main/schema_converter.py)) generates documentation from the MCP description and parameter definitions.

### Step 4: Expose Tools to aisuite

The resulting wrappers are standard Python callables compatible with aisuite's tool-calling interface. You can pass them directly to `client.chat.completions.create()` via the `tools` parameter or cache them for reuse across multiple chat sessions.

## Practical Implementation Examples

The following examples demonstrate the complete workflow from configuration dictionary to functional tool integration.

### Basic MCP Configuration

Define a minimal configuration for a filesystem MCP server using stdio transport:

```python
mcp_cfg = {
    "type": "mcp",
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
    # Optional: "use_tool_prefix": True, "allowed_tools": ["read_file"]

}

```

### Convert Config to Callable Tools

Use `MCPClient` to validate the configuration and generate callable wrappers:

```python
from aisuite.mcp.client import MCPClient

# Validate and create client

client = MCPClient.from_config(mcp_cfg)

# Retrieve list of callable tools

tools = client.get_callable_tools()

# Inspect wrapper metadata

print(tools[0].__name__)          # e.g., "read_file"

print(tools[0].__doc__)           # Formatted docstring

print(tools[0].__annotations__)   # {'path': str, 'encoding': Optional[str]}

```

### Convenience Helper Method

For streamlined workflows, use the `get_tools_from_config` class method to combine validation and wrapper generation:

```python
from aisuite.mcp.client import MCPClient

tools = MCPClient.get_tools_from_config(mcp_cfg)

# Returns list of ready-to-call wrappers

```

### Integration with aisuite Chat Completions

Pass the converted tools directly into your chat completion requests:

```python
import aisuite as ai

assistant = ai.Client()

response = assistant.chat.completions.create(
    model="openai:gpt-4o",
    messages=[{"role": "user", "content": "List the files in the project root"}],
    tools=tools,
    max_turns=2,
)

print(response.choices[0].message.content)

```

### Handling Multiple MCP Servers

When loading tools from multiple MCP servers, enable prefixing to avoid naming collisions:

```python
mcp_cfg["use_tool_prefix"] = True
prefixed_tools = MCPClient.get_tools_from_config(mcp_cfg)

print(prefixed_tools[0].__name__)   # e.g., "filesystem__read_file"

```

## Key Source Files and Architecture

Understanding the module structure helps debug and extend the conversion pipeline:

- **[`aisuite/mcp/config.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/config.py)**: Validates and normalizes MCP dictionaries, determines transport type, and fills default values.
- **[`aisuite/mcp/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/client.py)**: Manages MCP server connections, discovers available tools, and orchestrates wrapper creation.
- **[`aisuite/mcp/tool_wrapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/tool_wrapper.py)**: Implements `MCPToolWrapper` and signature generation for Python callable compatibility.
- **[`aisuite/mcp/schema_converter.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/schema_converter.py)**: Translates JSON Schema definitions into Python type annotations and docstrings.

## Summary

- **Configuration Validation**: The `validate_mcp_config` function ensures MCP dictionaries contain required fields and proper transport settings.
- **Client Instantiation**: `MCPClient.from_config` establishes server connections and discovers available tools.
- **Wrapper Generation**: `create_mcp_tool_wrapper` converts MCP tool schemas into Python callables with proper type annotations and signatures.
- **Convenience Method**: `MCPClient.get_tools_from_config` provides a single-step conversion from config dictionary to callable list.
- **Seamless Integration**: Converted tools integrate directly with `aisuite.Client().chat.completions.create()` via the `tools` parameter.

## Frequently Asked Questions

### What transport protocols does aisuite support for MCP connections?

aisuite supports both **stdio** (subprocess-based) and **HTTP** transports. The `get_transport_type` function in [`aisuite/mcp/config.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/config.py) automatically detects the appropriate transport based on the configuration dictionary fields, defaulting to stdio when a `command` is specified.

### How does aisuite handle type safety for MCP tool parameters?

The `mcp_schema_to_annotations` function in [`aisuite/mcp/schema_converter.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/schema_converter.py) converts JSON Schema definitions into Python type hints. The `MCPToolWrapper` class then generates a proper `inspect.Signature` object, allowing aisuite to validate arguments before invoking the underlying MCP server.

### Can I filter which MCP tools are exposed as callables?

Yes. Include the optional `allowed_tools` key in your MCP configuration dictionary containing a list of specific tool names. The `MCPClient` only wraps tools matching these names, ignoring others provided by the server.

### What is the purpose of the `use_tool_prefix` configuration option?

Setting `use_tool_prefix` to `True` prepends the MCP server name to each tool name (e.g., `filesystem__read_file`), preventing naming collisions when loading tools from multiple MCP servers simultaneously. This is handled during the validation phase in [`aisuite/mcp/config.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/mcp/config.py).