A practical guide to the GenOS REST and MCP surfaces, based on the source contracts. Authentication, tenant scope and tool permissions are enforced by the GenOS server.
client → auth → tenant scope → permission and policy checks → MCP transport → structured resultSend a GenOS access token in Authorization: Bearer. MCP execution requires mcp:execute_safe and an explicit organization and project scope. Pass both tenant headers; the IDs must belong together and the authenticated principal must be authorized for them.
Authorization: Bearer <access-token>
X-Organization-Id: <organization-id>
X-Project-Id: <project-id>GenOS checks browser origins against the default allowlist and GENOS_ALLOWED_ORIGINS. Add the exact public site origin to that server setting before connecting from a browser. Do not route a shared access token through a public website server.
GENOS_ALLOWED_ORIGINS=https://genos.workThe HTTP envelope accepts toolName or tool_name and timeoutMs or timeout_ms. Tool arguments use the JSON schema for that tool; names are canonically snake_case. The example launches a local supervised orchestration and waits for its result.
curl --request POST "$GENOS_URL/api/mcp/execute" \
--header "Authorization: Bearer $GENOS_TOKEN" \
--header "X-Organization-Id: $GENOS_ORG" \
--header "X-Project-Id: $GENOS_PROJECT" \
--header "Content-Type: application/json" \
--data '{"toolName":"genos_orchestrate","args":{"mission":"Summarize the approved task","executor":"local","background":false},"timeoutMs":60000}'Use these read and safe-execution routes to inspect available tools, retrieve argument schemas, or exercise a tool through the configured MCP transport. A successful test call can execute the real downstream tool.
GET /api/toolsreadList visible tools.
GET /api/tools/:name/schemareadReturns the current input schema.
POST /api/tools/testmcp:execute_safe + tenantTests the configured MCP transport.
POST /api/tools/dry-runmcp:execute_safeSimulates against supplied VFS state; it does not execute the transport.
POST /api/mcp/executemcp:execute_safe + tenantExecutes the tool when registry and policy allow it.
This schema is version-sensitive; retrieve the live tool schema before relying on optional fields. The small example fixes the executor to local and foreground execution.
{
"mission": "string (required)",
"worker_assignments": "optional",
"strategy": "optional",
"background": false,
"executor": "local",
"provider": "optional",
"modelId": "optional"
}MCP tool arguments use snake_case. The REST envelope temporarily accepts camelCase aliases only for its own two fields. Do not send both aliases with conflicting values. MCP protocol version is genos.mcp/v1.
{
"toolName": "genos_replay",
"args": { "snapshot_id": "snap-example" },
"timeoutMs": 30000
}Check the HTTP status and the tool-specific response body. REST does not use one universal success envelope. Errors may include error.code, error.message, requestId, traceId and details.
400Invalid request or arguments401Missing or invalid token403Permission, scope or policy denied404Route or tool not found429Rate limited502Downstream MCP transport failed503Service, tool or safety gate unavailable504Deadline exceeded{
"error": {
"code": "ZERO_TRUST_DENIED",
"message": "Tool execution denied.",
"requestId": "req-example",
"traceId": "trace-example"
}
}The HTTP service exposes cheap health probes. gRPC and Rust CLI contracts are separate from REST and MCP; use the source documentation and proto definitions for those clients.
GET /healthz
GET /readyz
GET /livez
gRPC: 127.0.0.1:50051
MCP protocol: genos.mcp/v1These routes belong to the GenOSWork site, not the GenOS runtime. They publish read-only knowledge without credentials. OpenAPI describes their responses; llms.txt maps the content.
Each contract is pinned to the same V3 revision. Check the deployed runtime schema before making live calls.