MCP reference
Developer/Operator reference. Ordinary users can use the local workbench without implementing this protocol.
Published interface
The hosted endpoint is https://api.rulith.ai/mcp. Authenticate with the selected Agent's Bearer token and use the server's MCP initialization and tool discovery.
The deployed service exposes the following six tools. This table is generated from the deployed Java contract and tool guidance.
| Tool | Description exposed to the agent |
|---|---|
OpenCase | Start a business Case once its required businessKey values are known from the user's input or an actual Source result. |
ApplyBatch | Record facts, hypotheses, rules, goals or corrections as one batch on the shared graph. |
ApplyAction | Use an available Action and its public inputSchema from the current Board View. |
CloseCase | Request a terminal outcome for one Case using its returned root. |
QueryBoard | Read the Case directory, relevant facts, goal status, gaps and available Actions when the latest tool result lacks information needed for the next decision. |
ReadArtifact | Read data that a tool result supplied as an Artifact reference. |
Discovery and workflow
Start with QueryBoard without an invented Case root. Its default view lists available Actions and configured Case Types, including required business-key fields.
Use actual user or Source data for business keys. OpenCase can create a Case of a configured type or select an existing returned Case ID. Reuse the returned IDs instead of constructing your own.
ApplyBatch records a batch on the shared graph. New model assertions do not become Source evidence. Its result identifies created or reused nodes and reports warnings and withdrawn conclusions within the response limits.
ApplyAction takes the public input shape advertised for that Action. Hidden bound fields belong to the platform. A declaration in the action list does not guarantee the next call will pass current admission.
CloseCase requests a disposition for the returned root. Treat the resulting acceptance decision as authoritative. A rejected close is not completion.
Views are bounded
Use the advertised QueryBoard schema for roots and requested sections. Respect truncation: a partial view is not evidence that no other fact or Case exists. Query only the missing information needed for the next decision.
Artifact reads
Use the reference actually supplied by a result. ReadArtifact can return a chunk; honor its encoding, next offset and completion flag. An inaccessible artifact is not an empty artifact.
For a local Rulith Agent, permitted reads can go directly to its Worker material area. Third-party clients use the Gateway's permitted relay. Original material is not a Gateway-hosted upload. See Files and permissions.
Recovery and client responsibilities
The published client uses the deployed rulith/v1 metadata contract. Preserve the same accepted call identity across recovery. Do not invent a new Action call after a timeout or treat an unknown result as a safe failure.
Use a compatible published Rulith client for managed recovery. Custom clients must implement the published request and session contract in addition to the business tool schemas returned by tools/list.
There is no separate /mcp/host setup step in this guide. Account and device management use the control plane; Worker execution uses its own Connection. None of those credentials are interchangeable.
Version baseline
Java 6b1ddc3 / Rulith 0.8.17
The documentation snapshot records the deployed Gateway revision and published npm client, not the tip of development branches. New protocol names or fields in candidate designs are unavailable until a coordinated release makes them current.