soma

Soma

Soma is a batteries-included RMCP server runtime and shipping binary for bringing new agent capabilities online with as little custom Rust as possible. It locks in the production patterns that every server in the family keeps rediscovering: one compact MCP tool, stdio and Streamable HTTP transports, CLI parity, direct REST routes, auth/OAuth, observability, plugin packaging, web fallback, Docker/runtime samples, generated contracts, and release automation.

The repository can still scaffold a renamed project, but Soma is now a shipped runtime first. The default product path is to run soma in an explicit mode, drop provider files into providers/ (or point SOMA_PROVIDER_DIR elsewhere), and let the provider registry project those capabilities across MCP, CLI, REST, OpenAPI, Palette summaries, generated docs, and plugin metadata. Provider manifests also carry MCP-native prompt, resource, task, and elicitation metadata for the registry contract. Scaffolding is the path for creating a new distributable repo with the same locked-in runtime.

30-second path: install the soma binary -> soma status -> npx -y soma-rmcp mcp from an MCP client -> call the soma MCP tool through tools/call with {"action":"status"}.

Status: production RMCP runtime. Write-capable provider actions are allowed only when the provider declares them and destructive actions are gated.

Not for: an unauthenticated public gateway, a replacement for upstream service authorization, arbitrary untrusted code execution, or a multi-tenant security boundary by itself.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Configuration
• Authentication
• Safety And Trust Model
• Architecture
• Distribution Contract
• Development
• Verification
• Deployment
• Troubleshooting
• Related Servers
• Documentation
• License

Naming

Soma is the runtime product first and the template/export source second. Generated projects replace these names during scaffold post-processing, but the shipped soma command is the source of truth for product behavior.

Surface	Soma value	Generated-project pattern
Repository	jmagar/soma	<service>-rmcp or a documented product exception
Rust crate/package	soma	service-specific crate names
Canonical binary	soma	usually r<service> or the product name
npm package	soma-rmcp	<service>-rmcp
MCP tool	soma	usually <service>
Env prefix	SOMA_*	generated service prefix

Capabilities And Boundaries

Path	Use when	You author	Runtime supplies
Drop-in provider	You can describe a capability as a manifest, script, WASM module, OpenAPI operation, or upstream MCP call.	Files under providers/ with tools, prompts, resources, env needs, capability grants, and surface overlays.	MCP tool dispatch, dynamic CLI commands, direct REST routes, schema validation, auth policy, refresh, OpenAPI/Palette summaries, generated docs, and plugin metadata.
Static Rust provider	The capability needs native Rust, tight integration, or reusable crates.	A Rust provider/action registered with the provider registry.	The same MCP/CLI/REST/docs/plugin projection without per-surface rewrites.
Scaffolded product	You need a renamed repository, package identity, ports, plugins, Docker labels, and release metadata.	A scaffold_intent payload or cargo xtask scaffold options.	A compiling product repo, scaffold report, cargo-generate post-processing, and scaffold/export verification checks.
Custom profile	You need a narrower binary or deployment shape.	Cargo feature selection.	The same runtime crates behind local-adapter, server, and full profiles.

Batteries Included