5.Add an MCP

What is an MCP?

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between Large Language Model (LLM) applications and external data sources and tools. By utilizing MCP, you can enhance your AI agents’ capabilities by connecting them to a wide range of tools developed by both companies and the community. This integration allows your agents to perform tasks that require external data access or specialized processing beyond their built-in functionalities.

What do MCPs do?

• Execute specific business logic or API calls
• Interact with databases, file systems, or external services
• Perform data processing, calculations, or transformations
• Enable human-in-the-loop workflows with confirmation and input requirements
• Provide caching and performance optimization capabilities

What are the parts of an MCP?

• Server Definition: The MCP server class that specifies connection details
• Command Configuration: The command and arguments to run the MCP server
• Tool Integration: Automatic integration with Upsonic’s tool processing system
• Error Handling: Robust error management for production reliability

Core Principles For MCPs

When integrating MCP tools into your AI agents, ensure you define these elements:

• Clear Purpose: Each MCP should have a single, well-defined responsibility
• Proper Configuration: All connection details must be correctly specified
• Error Handling: Graceful failure handling with meaningful error messages
• Security: Verify the security and reliability of the MCP tool, especially if it involves handling sensitive data

Defining MCP Server Classes

The MCP server class definition is the foundation of your MCP integration. Follow these guidelines:

• Single Responsibility: Each MCP should do one thing well
• Clear Configuration: Use descriptive class names and proper command/argument setup
• Documentation: Write comprehensive docstrings that explain the MCP’s purpose and usage

Good MCP Definition:

class DatabaseMCP:
    """
    MCP server for SQLite database operations.
    Provides tools for creating tables, inserting data, and querying databases.
    """
    command = "uvx"
    args = ["mcp-server-sqlite", "--db-path", "/path/to/database.db"]

Bad MCP Definition:

class MCP:
    # Missing documentation and unclear purpose
    command = "uvx"
    args = ["some-server"]

MCP Best Practices

Security Considerations

Validate and secure your MCP configurations:

class SecureMCP:
    """
    MCP server with security considerations.
    """
    command = "uvx"
    args = ["mcp-server-sqlite", "--db-path", "/secure/path/database.db"]
    env = {"SECURE_MODE": "true"}  # Environment variables for security

Clear Documentation

Always provide comprehensive documentation:

class WellDocumentedMCP:
    """
    Clear description of what the MCP does.
    
    This MCP provides filesystem operations including:
    - Reading files
    - Writing files
    - Directory listing
    - File permissions management
    
    Security Note: Only operates within the specified directory.
    """
    command = "uvx"
    args = ["mcp-server-filesystem", "/allowed/directory"]

Let’s Create MCP Tools for a Database Management Agent

In this example, we’ll create a comprehensive database management system using MCP tools and show how to combine them with regular Upsonic tools.

uv pip install upsonic
# pip install upsonic

# Upsonic Docs: Add an MCP
# https://docs.upsonic.ai/guides/5-add-an-mcp

# Imports
from upsonic import Agent, Task

# Define an MCP Server
class DatabaseMCP:
    """SQLite database operations MCP server"""
    command = "uvx"
    args = ["mcp-server-sqlite", "--db-path", "/tmp/library.db"]

# Create Agent with MCP Tools
database_agent = Agent(
    model="openai/gpt-4o-mini",
    name="Database Agent",
    role="Database operations specialist",
    goal="Manage database operations efficiently"
)

# Create and Execute Task with MCP
task = Task(
    description="""Create a 'books' table with columns: id, title, author, year. 
    Insert 3 sample books. Then query and show all books.""",
    tools=[DatabaseMCP]
)

# Run the task
result = database_agent.print_do(task)
print(result)

Need more advanced features? The MCP integration supports many powerful configuration options including:

• Environment Variables: Pass environment variables to MCP servers for configuration
• Custom Arguments: Specify custom command-line arguments for MCP servers
• Error Handling: Robust error management for MCP server failures
• Tool Combination: Seamlessly combine MCP tools with regular Upsonic tools
• Structured Output: Use Pydantic models for structured MCP responses
• Workflow Integration: Create complex workflows using multiple MCP tools

For detailed examples and advanced patterns, see our comprehensive MCP Concept Documentation.