Soma

RMCP runtime for provider-backed agents with CLI, REST, HTTP MCP, plugins, and scaffold support.

API docs — rustdoc for every workspace crate plus the Redoc-rendered OpenAPI reference, deployed to GitHub Pages from main.

Soma is a batteries-included 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	dinglebear-ai/soma (formerly rmcp-template, then rtemplate-mcp — both still redirect)	dinglebear-ai/r<service>, or the bare product name; older servers still carry <service>-rmcp names behind redirects
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,