Expose a capability as an MCP server

Leumas turns its tools into MCP servers so any coding agent (Claude, Cursor, a customer's agent) can call them, and so they can be listed, metered, and priced in Leumas Studio. The engine that runs them is engines/mcp (from mcp-server-library); the SDK that scaffolds them is packages/mcp-kit.

The contract

An MCP server is a folder under engines/mcp/mcp-servers/<server-name>/:

engines/mcp/mcp-servers/<server-name>/
├─ server.json          # metadata + tool list (+ pricing)
└─ tools/
   ├─ <toolA>.js        # export default async function({ ...args }) { return result }
   └─ <toolB>.js

server.json:

{
  "name": "<server-name>",
  "description": "What this server does",
  "enabled": true,
  "tools": [
    { "name": "<toolA>", "description": "...", "inputs": [{ "key": "x", "type": "string", "required": true }], "price": 0 }
  ]
}

Each tool file default-exports an async function that takes an args object and returns a result. It should be a thin wrapper that calls the underlying capability (an engines/ adapter, a services/ endpoint, or a packages/ SDK) — never re-implement the logic.

Steps

1. Identify the capability to expose (an adapter in engines/domain, a service endpoint, an SDK).
2. Scaffold with packages/mcp-kit (createServer / registerTool) or by hand from the contract above.
3. Wire each tool to call the real capability (import the @leumas/* package or fetch the service). Keep tools thin.
4. Auto-registration — engines/mcp (loadServers.js) scans mcp-servers/ on start and exposes

GET /mcp (list) + POST /tool (execute) via leumas-api. No manual mounting.

1. Validate — smoke-test the handshake, tool list, and a sample POST /tool call (schema + result).
2. Distribute & price in Leumas Studio: enable the server, set per-tool price, and choose the

gate (membership entitlement and/or PassNode usage metering via packages/auth).

Rules

• Tools are thin adapters over existing capabilities — no business logic lives in a tool file.
• Every priced tool is gated through packages/auth (membership and/or PassNode) — enforced by the API, not the tool.
• Keep servers single-purpose; a "server" groups related tools for one capability.
• Distribution: hosted (called on Leumas infra) or copy-paste. There is no per-server

downloadable package — a @leumas-mcp/<name> family was described here for a long time and never existed, so anyone who followed that sentence went looking for something that was not there.

How a stranger's agent actually connects

Not by installing a server per capability. One package — leumas-mcp on npm (shared/packages/mcp-bridge, published unscoped with its @leumas/* deps inlined) — is a stdio ⇄ streamable-HTTP bridge pointed at an install:

npx -y leumas-mcp --url https://api.leumas.tech          # Leumas-hosted
npx -y leumas-mcp --url http://localhost:3000            # the customer's own Studio
npx -y leumas-mcp --url <origin> --site <id>             # one hosted MCP server

Everything an install exposes reaches the agent through that one connection, so a tool added here appears with no release of anything. pnpm bridge:build · pnpm bridge:release (the gate packs the tarball, installs it outside the repo and runs a real initialize through it).