Soma

Soma

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

[Docs] 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 -- mcpcargo 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/somacd soma
# Full platform mode: REST API + HTTP MCP + web fallback on :40060cargo run --bin soma -- serve
# Local binary: stdio MCPcargo run --bin soma -- mcp
# Local binary: CLIcargo run --bin soma -- greet --name Alice

Useful smoke checks:

curl http://localhost:40060/healthcargo run --bin soma -- statuscargo 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 providerscat > 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 secrets inside tool functions, not at module import time.

Provider manifests can declare:

• tools/actions exposed through MCP by default and through CLI/REST when their overlays opt in
• MCP-native prompt, resource, task, and elicitation metadata for the provider registry contract
• required environment variables and redaction rules
• filesystem, network, browser, terminal, GitHub, and env capability grants
• limits, destructive-action metadata, examples, generated docs, plugin, and UI metadata

Supported provider kinds are static-rust, openapi, ai-sdk, wasm, mcp, python, langchain, and llamaindex. See docs/specs/dynamic-provider-runtime.md, docs/contracts/provider-manifest.schema.json, and docs/generated/provider-surfaces.md.

Scaffold A New Project

Use cargo xtask scaffold when the provider-first path needs to become a new repository with its own crate names, binary names, ports, plugin package, Docker metadata, release metadata, and docs. It can plan without touching files, generate with cargo-generate plus the Rust post-processor, write docs/scaffold-report.md, and verify the generated export shape.

Plan from a short service name:

cargo xtask scaffold --name myservice --category upstream-client --port auto --plan

Plan from MCP scaffold_intent JSON:

cargo xtask scaffold --intent scaffold-intent.json --plan

Generate into an output parent directory:

cargo xtask scaffold --intent scaffold-intent.json --apply ../generated

Verify an existing generated project:

cargo xtask scaffold --verify ../generated/myservice-mcp

Print a path-aware follow-up plan for adapting the generated stub:

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

Materialize starter artifacts from an action manifest:

cargo xtask scaffold \  --write-action-starters ../generated/myservice-mcp \  --actions actions.json

Add starter action snippets:

cargo xtask scaffold \  --intent scaffold-intent.json \  --actions actions.json \  --plan

Example action manifest:

{  "actions": [    {      "name": "list_things",      "description": "List visible things.",      "scope": "read",      "params": [        { "name": "kind", "type": "string", "required": false }      ]    }  ]}

Use:

• --category upstream-client for a lean local adapter around an existing API.
• --category application-platform for API + CLI + MCP + web defaults.
• --no-cargo-check only when you need fast static verification while iterating.

See docs/SCAFFOLD.md, docs/CARGO_GENERATE.md, and docs/contracts/scaffold-intent.schema.json for the full scaffold contract.

Architecture

The runtime keeps product behavior behind the provider registry. Every external surface is a thin parser/formatter around the same provider snapshot and service runtime, so dropping a provider does not require hand-editing MCP, CLI, REST, OpenAPI, plugin, or docs code.

ProviderRegistry  crates/soma/application/src/provider_registry.rs  Validates provider manifests, computes snapshots/fingerprints, indexes tools,  prompts, resources, CLI commands, REST routes, and MCP primitives.
Provider sources  crates/soma/application/src/providers/  Static Rust, file-backed JSON manifests, TypeScript AI SDK sidecars, Python  LangChain/LlamaIndex sidecars, WASM, OpenAPI-backed providers, and upstream  MCP providers.
SomaService  crates/soma/application/src/service.rs  Built-in product/service logic used by the static Rust provider.
Transport shims  crates/soma/cli/src/lib.rs        CLI parser and output formatting.  crates/soma/mcp/src/tools.rs      MCP JSON args to service calls.  crates/soma/api/src/api.rs        REST extractors to service calls.  apps/soma/src/http.rs             Axum router, auth, MCP, API, web fallback.
Built-in action metadata  crates/soma/domain/src/actions.rs  Native action metadata, validation, cached catalog/help, and native dispatch.

The thin-shim rule is strict:

1. Parse input at the surface.
2. Call the provider registry or service runtime.
3. Return or print the result.

Do not put business rules in CLI, MCP, REST handlers, or the binary entrypoint (apps/soma/src/bin/soma.rs / apps/soma/src/bootstrap.rs).

Runtime Surfaces

The canonical binary can run the whole app from one executable:

soma serve       # HTTP server: REST API + Streamable HTTP MCP + web fallbacksoma mcp         # stdio MCP transportsoma status      # CLI command through the same binary

Local adapter mode is optimized for plugin/local use:

soma mcp                # stdio MCP transportsoma greet --name Alice # CLI commandsoma doctor             # operator pre-flight checkssoma watch              # poll /health and emit state changessoma setup check        # plugin/appdata setup checks

Every explicit runtime mode loads the provider registry. File providers default to ./providers and can be moved with SOMA_PROVIDER_DIR. CLI startup, MCP dispatch, and dynamic REST routes refresh file providers before execution, then enforce the active provider snapshot's schema, surface, scope, capability, destructive-action, and response-limit rules.

HTTP routes in the server profile:

REST is direct-route-only: there is no /v1/soma action envelope. MCP remains one soma tool with an action argument.

MCP Tool Reference

The runtime exposes one compact MCP tool, soma, with an action argument. Built-in actions and dropped provider tools share that same dispatch path. This keeps MCP discovery small while allowing the provider catalog to grow behind the single tool.

Python provider lifecycle administration is exposed through the same compact tool with these explicit actions:

• environment cache: python_environment_status, python_environment_prune_plan, python_environment_prune, python_environment_repair, and python_environment_update;
• persistent workers: python_worker_status, python_worker_cancel, and python_worker_reset;
• provider generations: python_generation_status and python_generation_rollback;
• Python-to-component graduation: python_graduation_status and confirmed python_graduation_apply.

Built-in business actions keep MCP + CLI + REST parity unless there is a protocol reason they cannot. elicit_name and scaffold_intent are MCP-only because they rely on MCP elicitation. serve, mcp, doctor, watch, setup, and package are CLI operator commands, not business actions.

Dropped provider tools are MCP-enabled by default and REST-executable through POST /v1/tools/{action} unless the tool explicitly sets rest.enabled=false. A rest overlay can add a custom route, method, and OpenAPI metadata; the generic route remains the web/adapter-safe execution shape. CLI exposure is opt-in through each tool's cli overlay. Provider prompts, resources, tasks, and elicitation forms are part of the provider manifest contract and registry index; they are not mirrored to CLI or REST by default.

CLI Reference

The soma binary exposes operator commands and provider-backed actions through the same registry snapshot used by MCP:

soma greet --name Alicesoma echo --message hellosoma statussoma helpsoma providers validatesoma providers inspectsoma providers test statussoma providers list --dir ./examples/providerssoma providers lint --dir ./examples/providerssoma providers status --dir ./examples/providerssoma doctorsoma setup checksoma package generate --check

Provider tools opt in to CLI exposure with a cli overlay. Dynamic CLI flags are derived from the provider input schema, so the generated provider catalogs remain the source of truth for current action shapes.

Safety And Trust Model

MCP callers never provide API keys, OAuth secrets, bearer tokens, passwords, or other credentials in tool arguments. Credentials live in environment variables, config files, appdata, or the upstream provider runtime.

Provider manifests are validated before dispatch. The registry enforces surface opt-ins, JSON Schema input validation, auth scope, declared host capabilities, destructive-action confirmation, response-size limits, and structured provider errors. Python, LangChain, LlamaIndex, and TypeScript provider files are trusted local code; WASM providers run through the sandboxed WASM provider path; OpenAPI and MCP providers delegate trust to their configured upstream service.

Authentication

The HTTP server supports four auth policies:

The startup guard refuses non-loopback unauthenticated binds unless bearer, OAuth, or trusted-gateway mode is configured. /health, /readyz, /status, and /openapi.json are public by design and return only safe runtime metadata.

See docs/AUTH.md for the detailed auth model.

Configuration

Values load from config.toml, local appdata files, and environment variables; explicit environment variables win. The built-in offline provider works without real credentials, but generated projects should mark their real upstream/platform credentials as required.

Keep SOMA_MCP_TRACE_HEADERS=off unless the server is bound to loopback or a trusted gateway strips or overwrites trace headers from untrusted clients. Bearer/OAuth authentication alone is not that trust boundary. See docs/TRACE_CONTEXT.md for the complete inbound-only trace-header contract.

Samples:

• .env.example for secrets, URLs, and runtime env.
• config.soma.toml for non-secret defaults.

Provider callback paths default to /auth/google/callback, /auth/authelia/callback, and /auth/github/callback; callback and scope overrides are listed in docs/ENV.md. GitHub OAuth Apps do not provide an upstream refresh token, so GitHub-authenticated sessions do not receive a local refresh token and must sign in again after their access token expires. See docs/AUTH.md for provider selection and security details.

Development

# Build profilescargo build --bin soma --no-default-features --features local-adaptercargo build --bin soma --no-default-features --features servercargo build --bin soma --features full
# Run checkscargo fmt -- --checkcargo clippy --all-targets -- -D warningscargo nextest runcargo xtask contract-auditcargo xtask generate-provider-surfaces --check
# Common just recipesjust dev                 # loopback HTTP server with local no-authjust mcp                 # stdio MCPjust greet               # CLI smoke testjust doctor              # pre-flight checkjust build-local         # local adapter binaryjust build-full          # web assets + full platform binaryjust verify              # fmt, lint, check, testjust check-docs          # generated docs/metadata currentjust scaffold-contract-checkjust validate-plugin

cargo xtask ci runs the main local CI sequence. Optional tools such as cargo-nextest, taplo, and cargo-audit are used when installed.

Workspace layout

41 cargo members:

rmcp is pinned exactly — rmcp = { version = "=3.1.0", default-features = false } in [workspace.dependencies], duplicated on the rmcp-client alias entry because TOML cannot cross-reference. Bump both together.

[workspace.package] is the source of truth for Rust edition and MSRV: new members inherit edition = "2024" and rust-version = "1.97.1" with edition.workspace = true and rust-version.workspace = true. Shared crates also inherit workspace lints so architecture and module-layout policy stays consistent across the fleet.

Client Configuration

Streamable HTTP:

{  "mcpServers": {    "soma": {      "url": "http://localhost:40060/mcp",      "headers": {        "Authorization": "Bearer YOUR_TOKEN"      }    }  }}

Stdio:

{  "mcpServers": {    "soma": {      "command": "/path/to/soma",      "args": ["mcp"],      "env": {        "SOMA_API_URL": "https://api.example.com",        "SOMA_API_KEY": "YOUR_API_KEY",        "RUST_LOG": "warn"      }    }  }}

For generated projects, replace soma, SOMA_*, tool names, scopes, and paths with the generated service names.

Plugin Surfaces

The repo ships one shared Soma plugin package under plugins/soma for Claude Code, Codex, and Gemini surfaces. Plugin manifests are versionless; release tooling derives version identity from git state. The plugin package can use the local stdio adapter and includes setup/doctor support for appdata and environment files.

Primary docs:

• docs/PLUGINS.md
• plugins/soma/.codex-plugin/README.md
• plugins/soma/skills/soma/SKILL.md
• plugins/soma/skills/scaffold-project/SKILL.md

Distribution Contract

The soma release component is defined in release/components.toml. Version-bearing artifacts must stay aligned across the Rust package, Cargo.lock, server.json, the npm package, generated OpenAPI metadata, OCI image identifiers, and the changelog.

Plugin manifests stay versionless. Marketplace and plugin release identity is derived from git/package metadata, while server.json and generated provider surface docs describe the currently shipped runtime surface. Run cargo xtask check-version-sync, cargo xtask generate-provider-surfaces --check, and cargo xtask check-docs before publishing release metadata.

Web UI

The web feature serves the static export bundled by soma-web. Editable frontend source lives in apps/web, and cargo xtask sync-web-source copies that source into the Rust crate bundle.

Useful commands:

cargo xtask build-webcargo xtask sync-web-sourcecargo xtask check-web-source-syncpnpm -C apps/web validate

Generated projects that do not need a human UI should use local-adapter, server, or a custom feature set without web.

Deployment

The full platform profile is designed for one deployable soma binary. The repository also includes Docker and Compose samples:

• config/Dockerfile
• docker-compose.prod.yml
• entrypoint.sh

When adapting a generated project, verify the canonical binary name, exposed port, healthcheck port, image labels, service user/group, data volume, and required environment variables. The scaffold verifier catches several scaffold-only artifacts, but deployment files still need service-specific review before publishing an image.

When Drop-In Providers Are Not Enough

Most new capabilities should start as provider files. Reach for native Rust or a scaffolded product when you need a reusable crate boundary, richer service state, custom clients, background jobs, a dedicated package identity, or hand-tuned transport behavior.

For a generated product, start by printing the profile-aware checklist:

cargo xtask scaffold --adapt-plan ../generated/myservice-mcp

Then generate reviewable starter artifacts for the repetitive action wiring:

cargo xtask scaffold \  --write-action-starters ../generated/myservice-mcp \  --actions actions.json

This writes docs/action-starters/ in the generated project with snippets for action metadata, MCP dispatch, CLI variants, service stubs, and test coverage.

1. Replace the stub client in crates/soma/client/src/client.rs only when the provider file path is not enough.
2. Put domain logic in crates/soma/application/src/service.rs or focused service modules.
3. Register native provider/action metadata so MCP, CLI, REST, docs, and plugins stay registry-driven.
4. Regenerate MCP schema docs, provider surface docs, and OpenAPI so generated surfaces reflect the provider registry.
5. Add REST handlers only for infrastructure routes; business actions should stay registry-backed direct routes.
6. Update config fields and env prefixes in crates/soma/config/src/config.rs.
7. Update .env.example, config.soma.toml, plugin options, and setup mappings.
8. Update server.json, plugin metadata, repository URLs, Docker labels, and release metadata.
9. Add tests for MCP dispatch, CLI parsing, REST routes, provider loading, and service behavior.
10. For generated/exported projects, run scaffold verification plus the project's local quality gates.

For public repositories, also review tracked docs, generated metadata, CI runner configuration, and secret-scanning allowlists before publishing.

Troubleshooting

• soma doctor checks local configuration, appdata, and connectivity.
• soma providers validate confirms provider manifests and compiled schemas against the loaded, live registry.
• soma providers inspect shows provider surfaces, capability posture, and generated action inventory.
• soma providers list|lint|status inspect drop-in provider files on disk without loading the registry or executing any handler — safe to run before the runtime touches TS/WASM/MCP/OpenAPI providers. See docs/PROVIDERS.md.
• Stdio mode keeps logs quiet so JSON-RPC is not corrupted; use HTTP mode or file logs when investigating noisy startup failures.
• If generated docs drift, run cargo xtask generate-provider-surfaces --write and then re-run the --check command.

Related Servers

• runifi - UniFi controller REST API bridge.
• rtailscale - Tailscale API bridge for devices, users, and tailnet operations.
• unraid - Unraid monorepo: Python and Rust GraphQL MCP servers plus Unraid plugins.
• rapprise - Apprise notification fan-out bridge for many delivery backends.
• rgotify - Gotify push notification bridge for sends, messages, apps, and clients.
• rarcane - Arcane Docker management bridge for containers and related resources.
• yarr - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
• rytdl - Media download and metadata workflow server.
• synapse - Local Synapse workflow server for scout and flux actions.
• cortex - Syslog and homelab log aggregation MCP server.
• axon - RAG, crawl, scrape, extract, and semantic search project.
• labby - Homelab control plane and MCP gateway project.
• lumen - Local semantic code search MCP server.

Documentation

Verification

Product runtime gates:

cargo xtask check-docscargo xtask generate-provider-surfaces --checkcargo xtask check-schema-docs --checkcargo xtask check-openapi --checkcargo xtask validate-plugin-layoutcargo xtask check-version-syncjust verify

Scaffold/template gates are a separate lane. Run them when a change touches the scaffold contract, cargo-generate post-processing, or generated-project output:

cargo xtask check-scaffold-intent-contractcargo xtask scaffold --verify ../generated/myservice-mcpcargo xtask check-cargo-generate

Use targeted checks while iterating, then run the broader product and affected scaffold gates before release.

License

Original Dinglebear-authored portions of this project are licensed under AGPL-3.0-only. Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See LICENSING.md.