MCP Server Overview¶

The Thoth MCP (Model Context Protocol) Server provides a framework for building remote tool and resource servers that can be accessed via the MCP protocol.

Architecture¶

The server is built on top of the official MCP Python SDK and provides:

Tool Registration: Define and register custom tools
Resource Management: Manage and serve resources
Async Support: Full async/await support for modern Python
Type Safety: Complete type annotations throughout
Extensibility: Easy to extend with new tools and resources

Core Components¶

Server Class¶

The thoth.mcp_server.server.ThothMCPServer class is the main entry point:

from thoth.mcp_server import ThothMCPServer

server = ThothMCPServer(
    name="my-server",
    version="1.0.0"
)

Protocol Handlers¶

The server implements the following MCP protocol handlers:

list_tools(): Returns available tools
call_tool(): Executes a tool by name
list_resources(): Returns available resources
read_resource(): Reads a resource by URI

Available Tools¶

See Thoth MCP Tools Documentation for complete tool documentation.

Ping Tool¶

A simple connectivity test tool:

{
  "name": "ping",
  "arguments": {
    "message": "Hello!"
  }
}

Response: "pong: Hello!"

Running the Server¶

Command Line¶

python -m thoth.mcp_server.server

Programmatically¶

from thoth.mcp_server import run_server

run_server()

Async Mode¶

import asyncio
from thoth.mcp_server import ThothMCPServer

async def main():
    server = ThothMCPServer()
    await server.run()

asyncio.run(main())

Extending the Server¶

Adding New Tools¶

To add a new tool, modify the _setup_handlers() method:

@self.server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="my_tool",
            description="My custom tool",
            inputSchema={
                "type": "object",
                "properties": {
                    "param": {
                        "type": "string",
                        "description": "A parameter"
                    }
                },
                "required": ["param"]
            }
        )
    ]

@self.server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "my_tool":
        # Handle tool logic
        result = f"Processed: {arguments['param']}"
        return [TextContent(type="text", text=result)]

Adding Resources¶

Resources can be added similarly through the resource handlers:

@self.server.list_resources()
async def list_resources() -> list[Resource]:
    return [
        Resource(
            uri="thoth://my-resource",
            name="My Resource",
            description="A custom resource"
        )
    ]

@self.server.read_resource()
async def read_resource(uri: str) -> str:
    if uri == "thoth://my-resource":
        return "Resource content"
    raise ValueError(f"Resource not found: {uri}")

Testing¶

See MCP Server Test Coverage for comprehensive testing documentation.