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. The package is a launcher for the Rust binary; install soma first or set SOMA_BIN to its absolute path.

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 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 fallback
soma mcp         # stdio MCP transport
soma status      # CLI command through the same binary

Local adapter mode is optimized for plugin/local use:

soma mcp                # stdio MCP transport
soma greet --name Alice # CLI command
soma doctor             # operator pre-flight checks
soma watch              # poll /health and emit state changes
soma 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 Alice
soma echo --message hello
soma status
soma help
soma providers validate
soma providers inspect
soma providers test status
soma providers list --dir ./examples/providers
soma providers lint --dir ./examples/providers
soma providers status --dir ./examples/providers
soma doctor
soma setup check
soma 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 profiles
cargo build --bin soma --no-default-features --features local-adapter
cargo build --bin soma --no-default-features --features server
cargo build --bin soma --features full

# Run checks
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo nextest run
cargo xtask contract-audit
cargo xtask generate-provider-surfaces --check

# Common just recipes
just dev                 # loopback HTTP server with local no-auth
just mcp                 # stdio MCP
just greet               # CLI smoke test
just doctor              # pre-flight check
just build-local         # local adapter binary
just build-full          # web assets + full platform binary
just verify              # fmt, lint, check, test
just check-docs          # generated docs/metadata current
just scaffold-contract-check
just 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

35 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.

Known inconsistency: [workspace.package] declares no edition, so each member sets its own — currently 31 on edition 2021 and 4 on edition 2024. Since generated projects inherit this manifest shape, prefer hoisting edition = "2024" into [workspace.package] (with members using edition.workspace = true) over adding another per-crate edition line.

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-web
cargo xtask sync-web-source
cargo xtask check-web-source-sync
pnpm -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-docs
cargo xtask generate-provider-surfaces --check
cargo xtask check-schema-docs --check
cargo xtask check-openapi --check
cargo xtask validate-plugin-layout
cargo xtask check-version-sync
just 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-contract
cargo xtask scaffold --verify ../generated/myservice-mcp
cargo xtask check-cargo-generate

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

License

MIT