MCPAdapt: Multi-Agent Framework Adapter

Common errors

• ModuleNotFoundError: No module named 'fastapi'

  cause Core server dependencies like FastAPI, Uvicorn, or Pydantic are not installed.
  fix Install `mcpadapt` along with its required dependencies explicitly: `pip install mcpadapt fastapi uvicorn pydantic sse_starlette websockets`. Alternatively, install an adapter-specific extra like `pip install mcpadapt[crewai]` which should pull in server dependencies too.

• RuntimeError: This application requires Python 3.12 or newer.

  cause Attempting to run `mcpadapt` with an unsupported Python version.
  fix Upgrade your Python environment to 3.12 or later. Verify your active Python version with `python --version` and switch environments if necessary.

• ValidationError: Field required [type=missing, input_value={'a': 10}, input_type=dict]

  cause Input parameters provided to the MCPAdapt server via an agent client do not match the expected Pydantic schema of the adapted agent function.
  fix Review the function signature of your adapted agent and the expected input schema. Ensure all required parameters are provided, and their types match the agent's expectations defined by the adapter. Check server logs for more specific schema errors.

• AttributeError: 'CrewAIAdapter' object has no attribute 'some_method_that_was_removed'

  cause The underlying agentic framework (e.g., CrewAI) has changed its API, making the `mcpadapt` adapter version incompatible or requiring an update to `mcpadapt`.
  fix Check `mcpadapt`'s release notes for updates specific to your agentic framework. If an updated adapter version isn't available, consider pinning the framework's version to a compatible one, or adapt your agent code to match the current `mcpadapt` adapter's expectations.

Warnings

• breaking Python 3.12+ is required for `mcpadapt`.
  Fix: Ensure your Python environment is version 3.12 or newer. Using `pyenv` or `conda` can help manage multiple Python versions.
• gotcha The library is in `0.x.x` versioning, implying potential API instability.
  Fix: Pin `mcpadapt` to a specific minor version in your `requirements.txt` (e.g., `mcpadapt==0.1.20`) and review release notes for any breaking changes before upgrading.
• gotcha Adapter-specific framework version compatibility is crucial.
  Fix: Ensure the version of your agentic framework (e.g., CrewAI, SmolAgents) is compatible with the `mcpadapt` adapter version you are using. Refer to `mcpadapt`'s documentation and the respective framework's documentation for compatibility guidance, as API changes in one can break the other.

Install

• pip install mcpadapt Install core library
• pip install mcpadapt[crewai] Install with CrewAI adapter dependencies
• pip install mcpadapt[smolagents] Install with SmolAgents adapter dependencies

Imports

• MCPAdapt

  from mcpadapt import MCPAdapt

• CrewAIAdapter
  wrong:

  from mcpadapt.crewai import CrewAIAdapter

  correct:

  from mcpadapt.adapters.crewai import CrewAIAdapter

  Adapters are located in the `mcpadapt.adapters` submodule.
• SmolAgentsAdapter
  wrong:

  from mcpadapt.smolagents import SmolAgentsAdapter

  correct:

  from mcpadapt.adapters.smolagents import SmolAgentsAdapter

  Adapters are located in the `mcpadapt.adapters` submodule.

Quickstart

This quickstart demonstrates how to set up an MCPAdapt server using the SmolAgentsAdapter. It wraps a simple Python function (`add`) into an agent service, making it accessible via the MCP specification. The server can be run standalone using `mcp_server.run()` or integrated into an existing FastAPI application.

import uvicorn
from fastapi import FastAPI
from mcpadapt import MCPAdapt
from mcpadapt.adapters.smolagents import SmolAgentsAdapter

# Define a simple function for the agent
def add(a: int, b: int) -> int:
    """Adds two numbers."""
    return a + b

# Initialize the SmolAgentsAdapter with the function
smolagents_adapter = SmolAgentsAdapter(
    name="adder",
    description="An agent that adds two numbers.",
    func=add
)

# Create the MCPAdapt server
mcp_server = MCPAdapt(
    agent_id="adder_agent",
    adapter=smolagents_adapter,
    server_params={
        "host": os.environ.get('MCP_HOST', '127.0.0.1'), 
        "port": int(os.environ.get('MCP_PORT', '8000'))
    }
)

# To run the server (this will block):
# mcp_server.run()

# Alternatively, integrate with an existing FastAPI app (recommended for production):
app = FastAPI()
app.include_router(mcp_server.router)

# You can then run this FastAPI app using uvicorn:
# uvicorn your_module_name:app --host 127.0.0.1 --port 8000
# For testing, you could run:
# if __name__ == "__main__":
#     import os
#     os.environ['MCP_HOST'] = '127.0.0.1'
#     os.environ['MCP_PORT'] = '8000'
#     mcp_server.run()