liberrex-mcp-server (Python)

Publish a platform's tools on the Liberrex MCP mesh, so that Liberrex AI, Animatoria, the ERP and any other platform of the ecosystem can call them. It follows the shared mesh conventions: peer keys, per-call user identity, permissions, write control and [code] errors. The package also ships the Liberrex AI platform server (liberrex-mcp-server): agents, copilot and sales intelligence (next best action, next best product…) as tools.

• Python ≥ 3.10, built on the official mcp SDK v2. Stateless Streamable HTTP (any instance answers any call) or stdio.
• Pair it with liberrex-mcp-client on the calling side.
• TypeScript equivalent: @liberrex/mcp-server.

pip install liberrex-mcp-server

Publish your platform's tools

from typing import Optional
from liberrex_mcp_server import PeerRegistry, PlatformError, PlatformServer, ToolContext

server = PlatformServer("erp", title="Acme ERP", peers=PeerRegistry.from_env())

@server.tool(permission="invoices.read", category="finance")
def overdue_invoices(ctx: ToolContext, customer: Optional[str] = None, limit: int = 20) -> dict:
    """Overdue invoices the user can see, oldest first."""
    user = ctx.require_identity()            # who the call acts for: user_id, tenant_id, roles, locale
    rows = invoices.overdue(tenant=user.tenant_id, user=user.user_id, customer=customer, limit=limit)
    if rows is None:
        raise PlatformError("not_found", "Unknown customer")      # → "[not_found] Unknown customer"
    return {"items": rows}

@server.tool(permission="invoices.write", write=True)
async def send_reminder(ctx: ToolContext, invoice_id: str) -> dict:
    """Send a payment reminder."""
    ...

Then serve it:

app.mount("/mcp", server.asgi())       # FastAPI / Starlette; the endpoint answers at /mcp/
server.run_http(port=8765)             # standalone, at /mcp
server.run_stdio()                     # local desktop clients

The SDK checks these before your function runs:

Sync functions run in a worker thread, so they may block, for example on a database call. Use ctx.forward_meta() when a tool calls another platform: the same person and trace go along, with hops + 1.

Already integrated with the Liberrex copilot?

Publish every tool you declared with liberrex_copilot in one line. The schemas, permission checks and error codes stay the same:

from liberrex_mcp_server.copilot import publish_copilot
publish_copilot(server, copilot, user=lambda identity: load_user_with_roles(identity))

This is how Animatoria publishes its 43 tools at /mcp. The user callback lets your platform compute the user's roles itself, rather than trust the roles the caller sends.

Tools that already have a JSON Schema

server.raw_tool("lookup", description="…", input_schema={"type": "object", "properties": {...}},
                handler=lambda ctx, arguments: ...)

Peers (who may call)

liberrex-mcp-server new-key liberrex-ai     # prints a key for the caller and the sha256 entry for you

LIBERREX_MCP_PEERS='{"liberrex-ai": {"keys": [{"key": "sha256:…", "expires": "2027-01-31"}, "sha256:…"],
                                     "tenants": "*", "writes": false, "rate_per_minute": 300},
                     "erp": {"key": "sha256:…", "tenants": ["acme"], "roles": ["invoices.read"]}}'
LIBERREX_MCP_PEERS_FILE=/etc/erp/mcp-peers.json    # or: the same JSON in a file, re-read when it changes

Keep only hashes on the server, give each caller its own key, and grant writes only where needed. Rotate with an overlap: add the new hash to keys, give the caller the new key, then remove the old hash (or let its expires pass). python -m liberrex_mcp_server.keys <peer> also prints a key and its hash.

With LIBERREX_MCP_PEERS_FILE (FilePeerRegistry), the file is re-read when its mtime changes (checked at most every 2 s): revoke a caller without a restart. Invalid at startup → PeerConfigError; invalid later → logged, the previous peers stay; missing → no caller is accepted.

Audit

Every tool call (ok / refused / error) and every refused HTTP request (unauthorized, rate_limited) produces one event for PlatformServer(..., audit=fn) (default: a JSON line on the liberrex_mcp_server.audit logger; None: off): at, platform, event, tool, write, peer, user, tenant, trace_id, origin, hops, status, code, duration_ms (and client for HTTP events). Tool arguments are never included. The fields are the same in the TypeScript server; see MCP_MESH.md §6.

The Liberrex AI platform server

liberrex-mcp-server --check                     # credentials, peers, tools
liberrex-mcp-server --transport http --port 8765   # the mesh endpoint at /mcp (needs LIBERREX_MCP_PEERS)
liberrex-mcp-server                              # stdio for Claude Desktop / Cursor (acts as LIBERREX_USER_ID)

The 20 tools are:

Each calling user gets their own copilot session, minted for the user.id and tenant.id the calling platform sends. Recommendations are therefore computed from that user's own data, under their own roles.

Development

python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]" -e ../../mcp-client/python -e ../../python
.venv/bin/pytest      # 39 tests, including server ↔ client end to end over HTTP