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

SurfaceCall Pattern
MCPsoma(action="greet", name="Alice")
RESTPOST /v1/greet {"name":"Alice"}
CLIsoma 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"
}
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"
  ]
}