API Explorer

All surfaces (MCP, REST, CLI) call the same service methods.

Endpoint

POST/v1/greetDirect REST greeting action

POST/v1/echoDirect REST echo action

GET/v1/statusAuthenticated service status action

GET/v1/helpAction catalog and route help

GET/v1/capabilitiesREST route inventory

GET/healthLiveness probe (unauthenticated)

GET/statusRuntime status

POST/mcpMCP Streamable HTTP transport

GET/openapi.jsonGenerated OpenAPI schema for the REST surface

Surface Parity

Surface	Call Pattern
MCP	soma(action="greet", name="Alice")
REST	POST /v1/greet {"name":"Alice"}
CLI	soma greet --name Alice

greetREST + MCP + CLI

Return a greeting.

Parameters

namestringoptional— Name to greet. Omit to greet the world.

cURL

curl -X POST http://localhost:40060/v1/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice"}'

MCP equivalent

soma(action="greet", name="...")

Response

{
  "greeting": "Hello, Alice!",
  "target": "Alice"
}

echoREST + MCP + CLI

Echo a message back unchanged.

Parameters

messagestring— Message to echo back. Must not be empty.

cURL

curl -X POST http://localhost:40060/v1/echo \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!"}'

MCP equivalent

soma(action="echo", message="...")

Response

{
  "echo": "Hello!"
}

statusREST + MCP + CLI

Return server status and configuration info.

cURL

curl http://localhost:40060/v1/status

MCP equivalent

soma(action="status")

Response

{
  "status": "ok",
  "note": "stub"
}

python_environment_statusREST + MCP + CLI

Inspect immutable Python environment cache state without executing provider code.

cURL

curl http://localhost:40060/v1/python/environments

MCP equivalent

soma(action="python_environment_status")

Response

{}

python_environment_prune_planREST + MCP + CLI

Plan a bounded prune of stale non-ready Python environment cache entries.

Parameters

stale_before_unix_secondsstring— Only select non-ready cache entries last modified at or before this Unix timestamp.

max_entriesstringoptional— Maximum cache entries to inspect in this bounded operation (default 100, maximum 1000).

cURL

curl -X POST http://localhost:40060/v1/python/environments/prune-plan \
  -H "Content-Type: application/json" \
  -d '{"stale_before_unix_seconds":100,"max_entries":100}'

MCP equivalent

soma(action="python_environment_prune_plan", stale_before_unix_seconds="...", max_entries="...")

Response

{}

python_environment_pruneREST + MCP + CLI

Apply a bounded prune of stale non-ready Python environment cache entries.

Parameters

stale_before_unix_secondsstring— Only select non-ready cache entries last modified at or before this Unix timestamp.

max_entriesstringoptional— Maximum cache entries to remove in this bounded operation (default 100, maximum 1000).

confirmstring— Must be true to apply the destructive prune plan.

cURL

curl -X POST http://localhost:40060/v1/python/environments/prune \
  -H "Content-Type: application/json" \
  -d '{"stale_before_unix_seconds":100,"max_entries":100,"confirm":true}'

MCP equivalent

soma(action="python_environment_prune", stale_before_unix_seconds="...", max_entries="...", confirm="...")

Response

{}

python_environment_repairREST + MCP + CLI

Repair the immutable environment for one managed Python provider.

Parameters

provider_pathstring— Managed Python provider path, relative to the configured provider directory or absolute within it.

confirmstring— Must be true to mutate the provider environment lifecycle.

cURL

curl -X POST http://localhost:40060/v1/python/environments/repair \
  -H "Content-Type: application/json" \
  -d '{"provider_path":"Hello!","confirm":true}'

MCP equivalent

soma(action="python_environment_repair", provider_path="...", confirm="...")

Response

{}

python_environment_updateREST + MCP + CLI

Resolve, prepare, validate, and atomically activate an immutable update for one managed Python provider.

Parameters

provider_pathstring— Managed Python provider path, relative to the configured provider directory or absolute within it.

confirmstring— Must be true to mutate the provider environment lifecycle.

cURL

curl -X POST http://localhost:40060/v1/python/environments/update \
  -H "Content-Type: application/json" \
  -d '{"provider_path":"Hello!","confirm":true}'

MCP equivalent

soma(action="python_environment_update", provider_path="...", confirm="...")

Response

{}

python_worker_statusREST + MCP + CLI

Inspect persistent Python worker health, quarantine, restart counts, and bounded redacted logs.

cURL

curl http://localhost:40060/v1/python/workers

MCP equivalent

soma(action="python_worker_status")

Response

{}

python_worker_cancelREST + MCP + CLI

Cancel one active persistent Python invocation by terminating its process tree.

Parameters

providerstring— Loaded persistent Python provider name.

confirmstring— Must be true to interrupt or reset worker state.

cURL

curl -X POST http://localhost:40060/v1/python/workers/cancel \
  -H "Content-Type: application/json" \
  -d '{"provider":"Hello!","confirm":true}'

MCP equivalent

soma(action="python_worker_cancel", provider="...", confirm="...")

Response

{}

python_worker_resetREST + MCP + CLI

Clear one persistent Python worker crash-loop quarantine.

Parameters

providerstring— Loaded persistent Python provider name.

confirmstring— Must be true to interrupt or reset worker state.

cURL

curl -X POST http://localhost:40060/v1/python/workers/reset \
  -H "Content-Type: application/json" \
  -d '{"provider":"Hello!","confirm":true}'

MCP equivalent

soma(action="python_worker_reset", provider="...", confirm="...")

Response

{}

python_generation_statusREST + MCP + CLI

Inspect the active Python provider generation and bounded rollback history.

cURL

curl http://localhost:40060/v1/python/generations

MCP equivalent

soma(action="python_generation_status")

Response

{}

python_generation_rollbackREST + MCP + CLI

Atomically reactivate a retained Python provider generation.

Parameters

generation_idstring— Retained generation identifier to reactivate.

confirmstring— Must be true to replace the active generation.

cURL

curl -X POST http://localhost:40060/v1/python/generations/rollback \
  -H "Content-Type: application/json" \
  -d '{"generation_id":100,"confirm":true}'

MCP equivalent

soma(action="python_generation_rollback", generation_id="...", confirm="...")

Response

{}

python_graduation_statusREST + MCP + CLI

Inspect digest-bound Python graduation, conformance, activation, and rollback state.

Parameters

workspacestring— Absolute graduation workspace path.

cURL

curl -X POST http://localhost:40060/v1/python/graduation/status \
  -H "Content-Type: application/json" \
  -d '{"workspace":"Hello!"}'

MCP equivalent

soma(action="python_graduation_status", workspace="...")

Response

{}

python_graduation_applyREST + MCP + CLI

Scaffold, componentize, build, verify, compare, activate, or roll back a Python graduation workspace.

Parameters

operationstring— Graduation operation to perform.

workspacestring— Absolute graduation workspace path.

sourcestringoptional— Python source path required by the graduate operation.

componentstringoptional— Component path used by build, verify, and compare.

fixturesstringoptional— Conformance fixture path used by graduate and compare.

wheelhousestringoptional— Directory containing authenticated pure-Python dependency wheels for componentize-py.

confirmstring— Must be true to mutate graduation or live provider state.

cURL

curl -X POST http://localhost:40060/v1/python/graduation/apply \
  -H "Content-Type: application/json" \
  -d '{"operation":"Hello!","workspace":"Hello!","source":"Hello!","component":"Hello!","fixtures":"Hello!","wheelhouse":"Hello!","confirm":true}'

MCP equivalent

soma(action="python_graduation_apply", operation="...", workspace="...", source="...", component="...", fixtures="...", wheelhouse="...", confirm="...")

Response

{}

elicit_nameMCP only

Ask the MCP client to collect a name, then return a personalised greeting.

REST availability

elicit_name is MCP-only because it requires an interactive MCP peer.

MCP equivalent

soma(action="elicit_name")

Response

{
  "greeting": "Hello, Alice!",
  "target": "Alice",
  "elicited": true
}

scaffold_intentMCP only

Collect scaffold setup intent through MCP elicitation and return JSON for the scaffold-project skill.

REST availability

scaffold_intent is MCP-only because it requires an interactive MCP peer.

MCP equivalent

soma(action="scaffold_intent")

Response

{
  "kind": "soma_scaffold_intent",
  "schema_version": 1
}

helpREST + MCP + CLI

Show the action reference.

cURL

curl http://localhost:40060/v1/help

MCP equivalent

soma(action="help")

Response

{
  "actions": [
    "greet",
    "echo",
    "status",
    "help"
  ]
}