Choosing a Client Surface
Four interchangeable client surfaces call the same business logic, enforce the same permission actions, and return the same response shapes.
| Surface | Best for | Setup guide |
|---|---|---|
| REST API | Backend services in any language, custom integrations | API Reference |
SDK (@soat/sdk) | TypeScript and JavaScript applications | SDK Introduction |
CLI (soat) | Scripts, CI pipelines, local exploration | CLI Introduction |
| MCP server | Claude Desktop, Cursor, and other MCP-aware runtimes | Connecting an MCP Client |
Rules of thumb
- Building a product — SDK in TypeScript (typed from the OpenAPI specs); REST API in any other language.
- Automating or exploring — CLI; every API operation is a sub-command (
soat create-agent,soat list-documents). - Working from an AI assistant — MCP server from any MCP-compatible client.
What is identical across surfaces
- Authentication — a user JWT or an
sk_-prefixed API key (IAM & Policies). - Permissions — one
resource:Actionstring per operation (e.g.documents:CreateDocument) (Permissions Reference). - Data — one backend, one database; a resource created on one surface is visible on the others.
Field naming
REST API and SDK: snake_case body fields and path parameters (project_id, {agent_id}). MCP tool schemas: the same snake_case names (project_id); only tool names are kebab-case. CLI: kebab-case flags (--project-id).