ractogateway.mcp.server

RactoMCPServer — expose a ToolRegistry as a Model Context Protocol server.

Uses the low-level mcp.server.Server API so that our own ToolSchema.to_json_schema() schemas are forwarded verbatim to every MCP client — no re-introspection via FastMCP, no drift.

Requires the mcp package:

pip install ractogateway[mcp]

SSE transport additionally requires starlette + uvicorn:

pip install ractogateway[mcp-sse]

Quick start (stdio — for Claude Desktop / subprocess):

from ractogateway import ToolRegistry
from ractogateway.mcp import RactoMCPServer

registry = ToolRegistry()

@registry.register
def search(query: str, limit: int = 5) -> str:
    '''Search the knowledge base.'''
    return f"top {limit} results for {query!r}"

server = RactoMCPServer.from_registry(registry, name="my-tools")
server.run()  # blocks; talks MCP via stdin/stdout

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "my_package.server"]
    }
  }
}

class ractogateway.mcp.server.RactoMCPServer(name, *, description='', version='0.1.0')

Bases: object

Expose a ToolRegistry (or individual functions) as a Model Context Protocol server.

Supported transports

• stdio (default) — standard I/O; ideal for Claude Desktop and any subprocess-based MCP client.

• sse — HTTP Server-Sent Events; for remote / browser-based clients. Requires pip install ractogateway[mcp-sse].

type name:

str

param name:

Server name visible to MCP clients.

type description:

str

param description:

Optional human-readable description.

type version:

str

param version:

Server version string.

Example

from ractogateway import ToolRegistry
from ractogateway.mcp import RactoMCPServer

registry = ToolRegistry()

@registry.register
def add(a: int, b: int) -> int:
    '''Add two integers.'''
    return a + b

server = RactoMCPServer.from_registry(registry, name="math-tools")
server.run()  # stdio, blocking

classmethod from_registry(registry, *, name='ractogateway-server', description='RactoGateway MCP Server', version='0.1.0')

Build a server from a populated ToolRegistry.

Every registered callable becomes an MCP tool. Tools registered only as Pydantic models (no backing callable) are silently skipped.

Parameters:

• registry (ToolRegistry) – A ToolRegistry with one or more registered tools.

• name (str) – MCP server name shown to clients.

• description (str) – Optional server description.

• version (str) – Server version string.

Return type:

RactoMCPServer

Returns:

RactoMCPServer – Ready-to-run server instance.

add_tool(fn, *, name=None, description=None)

Register a single function as an MCP tool.

The function’s type annotations drive the JSON Schema; its docstring provides the description (overridable via description).

Parameters:

• fn (Callable[..., Any]) – The callable to expose. Both sync and async functions are supported.

• name (str | None) – Override the tool name (defaults to fn.__name__).

• description (str | None) – Override the tool description (defaults to the docstring).

Return type:

None

run(transport='stdio', *, host='0.0.0.0', port=8000)

Start the MCP server (blocking).

Parameters:

• transport (Literal['stdio', 'sse']) – "stdio" — standard I/O (default; integrates with Claude Desktop and subprocess clients). "sse" — HTTP Server-Sent Events (requires pip install ractogateway[mcp-sse]).

• host (str) – Bind host for SSE transport.

• port (int) – Bind port for SSE transport.

Return type:

None

get_asgi_app()

Return a Starlette ASGI app for SSE transport.

Use this to mount the MCP server into an existing web application rather than starting a standalone server with run().

Requires pip install ractogateway[mcp-sse].

Return type:

Any

Example

import uvicorn
from ractogateway.mcp import RactoMCPServer

server = RactoMCPServer.from_registry(registry, name="tools")
app = server.get_asgi_app()
uvicorn.run(app, host="0.0.0.0", port=8000)

property tool_names: list[str]

Sorted list of registered tool names.