Tools

MCP

The Genesis MCP server exposes the OneOS operations as tools for agents. It runs locally with npx over stdio.

Running the server


Command	`npx -y @lifesi/genesis-mcp@0.1.12`
Transport	stdio
Credential	`GENESIS_API_KEY`, or your saved `genesis login`
Gateway	`GENESIS_BASE_URL`, default `https://os.one.ml/api`
Tools	331, or 2 with `GENESIS_MCP_LAZY=1` (or `--lazy`)
Needs	Node.js 20.19 or later (tested on 20, 22 and 24)

Client setup for Claude Code, Claude Desktop and other clients is in Quickstart: MCP.

Each operation tool is named by its operation id (hives_create_project) and takes the same input as the operation: path and query parameters by name, the request body under body, and idempotency_key where the operation takes one. Every tool is listed at MCP tools.

Operations without a tool of their own are reachable through genesis_call:

{
  "name": "genesis_call",
  "arguments": { "operation": "hives_list_secrets", "arguments": { "project_id": "prj_…" } }
}

genesis_search_tools takes query (keywords such as "dns record") and an optional service, and returns matching operation ids with their input schemas.

Annotations

Tools carry the MCP annotations readOnlyHint, destructiveHint and idempotentHint; MCP tools shows each tool's. Clients can use them to ask before destructive calls.

Errors

A failed call returns isError: true with the error as JSON text: type, status, message and request_id, plus the gateway's code, required_scope and docs_url when the gateway raised it. The agent can say exactly what went wrong. See Errors.

Scope your agent's key

An agent can do whatever its key's scopes allow. Create a key per agent with only the scopes its task needs, and revoke it when the task ends. See Scopes.

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support