Soma

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 @dinglebear/soma 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.

Capabilities And Boundaries

Batteries Included

• One compact MCP service tool (soma) with action dispatch, so agent tool lists stay small even as provider catalogs grow.
• One canonical binary: soma with explicit serve, mcp, and CLI modes for REST API, Streamable HTTP MCP, stdio MCP, optional web UI, and local actions.
• Dynamic provider loading from .json, .ts, .py, .wasm, and .md files, plus native Rust providers and upstream MCP/OpenAPI provider kinds. A structured providers/{tools,prompts,resources}/ layout is supported alongside root-level files, including path-derived MCP resources (static files and dynamic .ts readers) with a path-traversal trust boundary.
• Provider manifest contracts for tools, prompts, resources, tasks, elicitation forms, env requirements, capability grants, and surface overlays.
• Shared validation, destructive-action confirmation, auth/scope enforcement, response limits, redaction, logging, metrics, generated OpenAPI, generated provider surface docs, plugin manifests, setup, doctor, and release tooling.

Soma owns the runtime projection, validation, auth policy, packaging, generated metadata, and scaffold automation. Provider code owns service-specific behavior and credentials. Upstream services own their own authorization and data model. Soma deliberately refuses to make credentials part of tool-call input and does not turn provider manifests into an unrestricted remote execution boundary.

Install

Use the npm launcher when an MCP client expects an npx command. During postinstall, the package downloads the matching Linux/x64 or Windows/x64 release archive, verifies its SHA256SUMS entry and GitHub build attestation, and installs the native binary inside the package. GitHub CLI 2.68 or newer is required for provenance verification.

npx -y @dinglebear/soma mcp

Use Cargo while developing the repo:

cargo run --bin soma -- mcp

cargo run --bin soma -- serve

Release builds publish GitHub Release binaries, Docker/OCI metadata, the @dinglebear/soma npm launcher, MCP registry metadata, and plugin package files from the same release component.

Product Profiles

Choose the amount of surface area you want without changing the provider authoring model.

Lower-level Cargo features are available when you need a custom shape:

Quickstart

Run the product as-is:

git clone https://github.com/dinglebear-ai/soma

cd soma

Full platform mode: REST API + HTTP MCP + web fallback on :40060

cargo run --bin soma -- serve

Local binary: stdio MCP

cargo run --bin soma -- mcp

Local binary: CLI

cargo run --bin soma -- greet --name Alice

Useful smoke checks:

curl http://localhost:40060/health

cargo run --bin soma -- status cargo run --bin soma -- doctor

Call the MCP endpoint directly:

curl -s -X POST http://localhost:40060/mcp \

-H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"greet","name":"Alice"}}}'

Drop In A Provider

The fastest path for a new server is provider-first. Add a provider manifest or module to providers/, then run the same binary. Use SOMA_PROVIDER_DIR when the provider catalog should live outside the working directory.

mkdir -p providers

cat > providers/hello-local.json <<'JSON' { "schema_version": 1, "provider": { "name": "hello-local", "kind": "static-rust", "title": "Hello Local" }, "tools": [ { "name": "hello_local", "description": "Return a deterministic hello payload from a dropped provider.", "input_schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" } } }, "cli": { "enabled": true, "command": "hello-local" }, "rest": { "enabled": true, "method": "POST", "path": "/v1/hello-local" }, "meta": { "result": { "message": "hello from a dropped provider" } } } ] } JSON

Call it through the dynamic CLI surface:

cargo run --bin soma -- hello-local --name Alice

Run the server and call the same provider over REST and MCP:

cargo run --bin soma -- serve

curl -s -X POST http://localhost:40060/v1/hello-local \ -H "Content-Type: application/json" \ -d '{"name":"Alice"}'

curl -s -X POST http://localhost:40060/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"soma","arguments":{"action":"hello_local","name":"Alice"}}}'

Plain Python functions can also be dropped directly into providers/:

PROVIDER = {"name": "math-tools", "kind": "python"}

def add(a: int, b: int) -> int: """Add two integers.""" return a + b

When TOOLS is absent, public functions defined in the module become tools. Sync and async functions are supported, and common Python type annotations are converted into input schemas.

Python provider files are trusted code. Soma imports them during provider catalog refresh to discover tools, then executes tool calls in a sidecar with a cleared environment plus only declared provider/tool env values. Catalog import does not receive provider env; read secret