Connect HTTP, SDK, CLI and MCP

Choose a client for the same authorized platform service.

HTTP, Python SDK, CLI and MCP use one service and the same contracts. Use the Python environment containing WorldFuzz 0.4.0rc6. Paths below are examples: use absolute workspace paths in unattended clients.

Local Python SDK

For your own loopback service in the quickstart, obtain its ephemeral bootstrap token in memory. Organization mode disables bootstrap.

import json
from urllib.request import urlopen
from worldfuzz.platform.sdk import Client

base = "http://127.0.0.1:8766"
with urlopen(base + "/bootstrap", timeout=5) as response:
    token = json.load(response)["token"]
client = Client(base, token)
resources = client.call("find_resources", {"profile": "movingai.octile.v1", "limit": 9})

Keep tokens out of code repositories, URLs, logs and screenshots. All task routes require a bearer token. Public documentation and UI assets do not grant access to results.

Organization login and scoped clients

An operator provisions the organization, principal, workspace and allowed operations first. Membership is separate from source data rights. A token must permit every internal step of a workflow, including preparation and result reads.

from getpass import getpass
from worldfuzz.platform.sdk import Client

base = "http://127.0.0.1:8766"
login = Client(base, "").call("organization_login", {
    "organization": "your-org", "principal": "your-principal",
    "workspace": "your-workspace", "password": getpass("Workspace password: "),
    "operations": ["run_goal", "compile_goal", "prepare_plan", "execute_plan",
                   "get_run", "get_result", "get_result_report", "find_resources"],
    "ttl_seconds": 3600,
})
if login["status"] != "ok":
    raise RuntimeError(login["error"]["code"])
client = Client(base, login["data"]["token"])

Missing, expired or revoked membership/token scope blocks the request and worker. include_artifacts also requires get_artifact_json. Do not request every operation to work around a denial; have the owner grant only the needed scope.

CLI against the same HTTP gateway

Save this non-secret placement configuration as remote.json, and supply WORLDFUZZ_SESSION_TOKEN through a protected environment. No token belongs in the file:

{"version":"1.0.0","kind":"remote_http","endpoint":"http://127.0.0.1:8766","token_env":"WORLDFUZZ_SESSION_TOKEN"}

python -m worldfuzz platform --placement remote.json run navigation --resource movingai:0 --case-index 0 --key my-nav-0 --max-seconds 30 --cpu-seconds 20 --memory-mib 256 --artifact-mib 1 --wait-seconds 30

The local --authority PATH variant uses an existing organization token directly. platform call OPERATION --json-file request.json supports all service operations. Discover exact schemas and examples in the generated reference.

MCP stdio

Configure an already installed MCP client with the same Python and placement file. The client must supply the existing token environment; do not include a secret in this configuration:

The supplied integration kit includes an optional worldfuzz Agent Skill and prepared MCP Registry metadata for the same Python stdio package. Install the skill into your client's project skill directory. Its compact instructions link to these pages and help preserve exact resource IDs, budgets, idempotency and evidence. No Registry or PyPI presence is established by these prepared files.

{
  "mcpServers": {
    "worldfuzz": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "worldfuzz", "platform", "--placement", "/absolute/path/to/remote.json", "mcp"]
    }
  }
}

worldfuzz is the server label. run_goal, find_resources and compare_results are tool names. solve_navigation is an adapter operation inside a tool argument, not a separate MCP tool. Let the host perform its own namespacing; never manually double-prefix a tool name.

The server supports stdio initialization, tool discovery/calls and the worldfuzz://capabilities resource. It does not advertise Streamable HTTP or experimental MCP Tasks. Append --read-only after mcp for an inspection-only connection; writes remain rejected. This configuration does not imply registry publication or client certification.