Skip to main content

​
Official SDK Compatibility

MCP

The mcp-use server framework is built on top of the official MCP Python SDK. This ensures full compatibility with existing MCP clients and tools that adhere to the Model Context Protocol. mcp-use extends the SDK’s core functionality, providing enhanced features without introducing breaking changes.

​
Zero Breaking Changes

mcp-use extends the official MCP Python SDK rather than replacing it, ensuring:
  • All existing MCP clients work out of the box
  • Full protocol compliance with MCP specifications
  • Easy migration from existing MCP servers
  • Enhanced features without breaking existing functionality

​
Compatibility Matrix

FeatureFastMCPmcp-useNotes
MCP Protocol✅✅Full compliance
Tools✅✅Same decorator API
Resources✅✅Same decorator API
Prompts✅✅Same decorator API
Documentation❌✅Built-in docs UI
Inspector UI❌✅Real-time monitoring
Enhanced Logging❌✅MCP method logging
Much more to come…❌✅Continuous enhancements

​
Migration Guide

​
From FastMCP

If you have an existing MCP server built with FastMCP, migration is as simple as changing the import:

​
Before (FastMCP)

from mcp.server import FastMCP

mcp = FastMCP()

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8000)

​
After (mcp-use)

from mcp_use.server import FastMCP

mcp = FastMCP()

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8000)
That’s it! Just change the import and you get all the enhanced features:
  • Built-in inspector UI at /inspector
  • Enhanced logging with MCP method information
  • Documentation at /docs
  • OpenMCP configuration at /openmcp.json
  • Configurable paths for all endpoints

​
Key Improvements

  1. Drop-in Replacement: Same FastMCP API with enhanced features
  2. Built-in Documentation: Automatic OpenAPI/Swagger docs at /docs
  3. Inspector UI: Real-time monitoring and testing at /inspector
  4. Enhanced Logging: MCP method information in structured logs
  5. Configurable Paths: Customize all endpoint paths
  6. Much More Coming: Continuous feature additions

​
Protocol Compliance

mcp-use maintains full compliance with the MCP protocol specifications:
  • Tool Discovery: Implements tools/list and tools/call endpoints
  • Resource Management: Implements resources/list and resources/read endpoints
  • Prompt Templates: Implements prompts/list and prompts/get endpoints
  • Error Handling: Proper error responses with MCP-compliant error codes
  • Session Management: Full support for MCP session lifecycle

​
Client Compatibility

All MCP clients that work with the official SDK will work with mcp-use servers:
  • Claude Desktop: Full compatibility
  • ChatGPT: Full compatibility
  • Custom MCP Clients: Full compatibility
  • mcp-use Client: Enhanced compatibility with additional features

​
Testing Compatibility

You can test your mcp-use server with any MCP client: 
# Test with mcp-use client
from mcp_use.client import MCPClient

config = {
    "mcpServers": {
        "my-server": {
            "url": "http://localhost:3001/mcp"
        }
    }
}

client = MCPClient(config)
session = await client.create_session("my-server")

# List tools
tools = await session.list_tools()
print("Available tools:", [tool.name for tool in tools])

# Call a tool
result = await session.call_tool("greet", {"name": "World"})
print("Result:", result)

​
Best Practices

​
Maintaining Compatibility

  1. Use Type Hints: Always use proper type hints for automatic schema generation
  2. Follow MCP Conventions: Use descriptive tool names and clear documentation
  3. Handle Errors Gracefully: Return proper error responses for invalid inputs
  4. Test with Multiple Clients: Verify compatibility with different MCP clients

​
Leveraging mcp-use Features

  1. Use Decorators: Take advantage of the simplified decorator-based API
  2. Enable Documentation: Use the built-in OpenAPI documentation
  3. Monitor with Inspector: Use the inspector UI for debugging and monitoring
  4. Structured Logging: Use JSON logging for better observability

​
Next Steps