How to Convert MCP Config Dicts to Callable Tools in aisuite

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 (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). 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).

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). 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 (lines 60-104) converts JSON Schema definitions into Python type hints.
• Signature Generation: The _create_signature method in 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) 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:

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:

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:

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:

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:

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: Validates and normalizes MCP dictionaries, determines transport type, and fills default values.
• aisuite/mcp/client.py: Manages MCP server connections, discovers available tools, and orchestrates wrapper creation.
• aisuite/mcp/tool_wrapper.py: Implements MCPToolWrapper and signature generation for Python callable compatibility.
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}