ezmcp - MCP Server: Streamlined Integration for AI Applications

Overview: What is ezmcp MCP Server?

ezmcp is a lightweight framework designed to simplify the creation of MCP-compatible servers, allowing developers to quickly build custom APIs that can be easily consumed by various AI applications through Model Context Protocol (MCP). Built on top of FastAPI and leveraging its decorator-based API model, ezmcp provides automatic parameter validation, type conversion, and schema generation, making it ideal for developing tools and services that need to support real-time communication via Server-Sent Events (SSE).

🔧 Core Features & MCP Capabilities

ezmcp offers several core features that cater to the needs of both developers and AI applications:

1. FastAPI-style Decorator API: ezmcp utilizes decorators similar to FastAPI, enabling the definition of tools with minimal code. This makes it straightforward for users to map functions to specific MCP calls.

2. Automatic Parameter Validation & Type Conversion: Tools defined within an ezmcp application automatically validate and convert input parameters, ensuring consistent behavior across different client applications.

3. Tool Schema Generation: ezmcp dynamically generates API schemas based on function signatures, providing clear documentation of available tools for both developers and MCP clients.

4. Built-in SSE Support: With built-in support for Server-Sent Events (SSE), ezmcp simplifies the implementation of real-time updates, a crucial aspect of MCP.

5. FastAPI-style Middleware Support: Similar to FastAPI, ezmcp allows middleware to be added, giving users the flexibility to implement custom application-wide behaviors.

6. Easy Integration with Existing Starlette Applications: ezmcp can seamlessly integrate into existing projects built on Starlette, offering a smooth transition for developers.

7. Interactive Documentation Page: ezmcp provides an interactive documentation page accessible via http://localhost:8000/docs, allowing users to explore and test tools interactively without leaving the developer environment.

⚙️ MCP Architecture & Protocol Implementation

ezmcp is designed to conform to the Model Context Protocol (MCP) standards. The protocol flow involves an AI application making calls through a MCP client, which then communicates with the ezmcp server. Below is an overview of this interaction:

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

MCP Client Compatibility

ezmcp supports a range of MCP clients, enabling seamless integration with popular AI applications:

MCP Client	Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	✅
Cursor	❌	✅	❌

🚀 Getting Started with Installation

Installation of ezmcp is straightforward, leveraging Python's package manager pip. You can install it using the following command:

pip install ezmcp

💡 Key Use Cases in AI Workflows

ezmcp can be integrated into a variety of AI workflows to enhance functionality. Here are two real-world examples to illustrate its potential:

Real-Time Data Analysis for Financial Applications

In a financial application, users may need up-to-the-minute analysis of market data. By utilizing ezmcp, this could involve defining tools that fetch and process market data in real-time. The tool can be triggered via an MCP client, with the server processing requests and sending updates to the client through SSE.

from ezmcp import ezmcp, TextContent

# Create an ezmcp application
app = ezmcp("financial-analysis")

# Define a tool for fetching market data in real-time
@app.tool(description="Fetch real-time financial market data")
async def fetch_market_data():
    """Fetch and process real-time financial market data."""
    # Simulate data fetching and processing
    return [TextContent(type="text", text=f"Market Data Update: XYZ")]

# Run the application
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

Interactive Note-Taking for Educational Tools

Educational tools can benefit from real-time interaction between a user and the server. Here, defining a tool that allows students to take notes in real-time and receive instant feedback could significantly enhance the learning experience.

from ezmcp import ezmcp, TextContent

# Create an ezmcp application
app = ezmcp("educational-note-taking")

# Define a tool for note-taking in real-time
@app.tool(description="Take notes with real-time response capabilities")
async def take_notes(message: str):
    """Allow students to take notes and receive instant feedback."""
    # Simulate note-taking and response processing
    return [TextContent(type="text", text=f"Note Received: {message}; Feedback: Good Answer")]

# Run the application
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8001)

🔌 Integration with MCP Clients

ezmcp supports multiple MCP clients, ensuring compatibility across different environments:

• Claude Desktop: Full support for tools and prompts.
• Continue: Supports tools and data resources but not prompts.
• Cursor: Limited support, primarily focused on tool integration.

📊 Performance & Compatibility Matrix

Performance testing of ezmcp has shown that it performs well under varying loads. The server is designed to handle multiple requests concurrently while maintaining low latency due to its lightweight nature. Below is a compatibility matrix highlighting the performance metrics and supported features:

MCP Client	Data Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	-
Cursor	-	✅	-

🛠️ Advanced Configuration & Security

ezmcp offers advanced configuration options and security features to tailor the server's behavior to specific needs:

• Environment Variables: You can set environment variables for API keys, logging settings, etc., directly in your shell or through a config.py file.

# config.py example
API_KEY = "your-api-key"

Sample Configuration Code

{
  "mcpServers": {
    "[server-name]": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-[name]"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

❓ Frequently Asked Questions (FAQ)

Q1: How do I ensure compatibility with different MCP clients?

ezmcp supports multiple clients like Claude Desktop, Continue, and Cursor. You can check the compatibility matrix to understand which features are supported across these platforms.

Q2: Can ezmcp handle complex data types and validation?

Yes, ezmcp automatically validates input parameters and converts them based on their type. This ensures that all incoming requests conform to expected formats before being processed by tools defined in your application.

Q3: How do I secure my server when integrating with MCP clients?

ezmcp supports securing your server by using API keys and configuring environment variables for sensitive information such as database credentials or authentication tokens.

Q4: Is ezmcp suitable for high-traffic AI applications?

Absolutely, the lightweight nature of ezmcp makes it ideal for handling high traffic. It is designed to manage a large volume of concurrent requests efficiently without compromising performance.

Q5: Can I customize my integration with Starlette apps using ezmcp?

Yes, ezmcp can seamlessly integrate into existing Starlette applications. This allows you to leverage your current project setup while still benefiting from the powerful features offered by ezmcp.

👨‍💻 Development & Contribution Guidelines

Contributions are welcomed and encouraged! If you'd like to contribute, please follow these guidelines:

1. Fork the Repository: Start by forking this repository on GitHub.
2. Create a Pull Request: Implement your changes, test thoroughly, and submit a pull request.

For more detailed information, refer to the contribution guide.

🌐 MCP Ecosystem & Resources

ezmcp is part of a broader ecosystem aimed at enhancing model context protocols for AI applications. Explore additional resources, such as:

• MCP Protocol Documentation: Find comprehensive documentation on Model Context Protocol.
• Community Forum: Join the community to share ideas and get support from fellow developers.

# Example Middleware
from starlette.requests import Request

from ezmcp import TextContent, ezmcp

app = ezmcp("my-app")

@app.middleware
async def process_time_middleware(request: Request, call_next):
    """Add a header with the processing time."""
    import time
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

@app.tool(description="Echo a message back to the user")
async def echo(message: str):
    """Echo a message back to the user."""
    return [TextContent(type="text", text=f"Echo: {message}")]

By integrating ezmcp into your AI application, you can ensure seamless communication with various MCP clients and enhance your development workflow.