How do I install Soma?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Soma need an API key?

The publisher lists these environment variables: SOMA_HOME, SOMA_PROVIDER_DIR, SOMA_API_URL, SOMA_API_KEY, RUST_LOG.

Soma MCP server

Q: When was Soma last checked?

Last checked 2026-11-07. RMCP runtime for provider-backed agents with CLI, REST, HTTP MCP, plugins, and scaffold support.

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.

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

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.

Target	Best fit	Default profile	Includes
Local agent adapter	Thin wrapper over dropped providers or an upstream API	`local-adapter`	CLI + stdio MCP in one local binary. No REST/Web mirror by default.
Shared API/MCP server	Service used by multiple clients or a gateway	`server`	CLI + REST API + Streamable HTTP MCP + stdio MCP + health/status routes + auth-capable runtime.
Full application platform	App owns state, jobs, dashboards, workflows, or human UI	`full`	`server` plus embedded web UI, OAuth, observability, and plugin support.
CLI-only or custom local tool	Scripts, operator utilities, one-machine tools	Custom feature set, usually starting from `cli`	CLI parser and shared service layer. The stock packaged local binary uses `local-adapter`, so CLI-only products may prune MCP or adjust binary feature gates.

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

Feature	Purpose
`cli`	CLI shim and command parsing.
`mcp`	MCP tool, schema, resource, prompt, and scope layers.
`mcp-stdio`	Local stdio MCP transport.
`api`	REST handlers and OpenAPI-backed business routes.
`auth`	Shared auth policy and bearer-token enforcement.
`oauth`	Google, Authelia, and GitHub OAuth/OIDC plus JWT issuance on top of `auth`.
`mcp-http`	Streamable HTTP MCP mounted in Axum.
`web`	Embedded static web UI fallback.
`observability`	Metrics/tracing hooks.
`plugin`	Plugin setup/support helpers.
`local-adapter`	Lean local binary: `cli` + `mcp-stdio`.
`server`	Deployable HTTP runtime profile: `cli` + `api` + HTTP MCP + stdio MCP.
`full`	Complete platform profile: local adapter, server, web, OAuth, observability, and plugin support.

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:

Parse input at the surface.
Call the provider registry or service runtime.
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:

Route	Purpose
`/mcp`	Streamable HTTP MCP transport.
`/health`	Unauthenticated liveness.
`/readyz`	Readiness check.
`/status`	Public redacted runtime status.
`/openapi.json`	Generated REST OpenAPI schema.
`/metrics`	Prometheus metrics when built with `observability`.
`/v1/capabilities`	REST route inventory.
`/v1/greet`, `/v1/echo`, `/v1/status`, `/v1/help`	Direct REST business routes.
`/v1/tools/{action}`	Generic REST execution route for dropped provider tools.
`/v1/{provider-route}`	Optional provider-declared REST route when a tool supplies a custom REST overlay.
`/mcp/.well-known/*`	OAuth metadata when OAuth is enabled.
`/*`	Embedded web UI fallback when built with `web`.

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.

Action	Scope	Cost	Transport	REST route	CLI	Parameters	Description
`greet`	`soma:read`	`cheap`	MCP + CLI + REST	`POST /v1/greet`	`soma greet [--name NAME]`	`name` (optional string)	Return a greeting.
`echo`	`soma:read`	`cheap`	MCP + CLI + REST	`POST /v1/echo`	`soma echo --message MSG`	`message` (required string)	Echo a message back unchanged.
`status`	`soma:read`	`cheap`	MCP + CLI + REST	`GET /v1/status`	`soma status`	none	Return server status and configuration info.
`python_environment_status`	`soma:write`	`cheap`	MCP + CLI + REST	`GET /v1/python/environments`	`soma python_environment_status`	none	Inspect immutable Python environment cache state without executing provider code.
`python_environment_prune_plan`	`soma:write`	`moderate`	MCP + CLI + REST	`POST /v1/python/environments/prune-plan`	`soma python_environment_prune_plan --json '{\`	`stale_before_unix_seconds` (required integer), `max_entries` (optional integer)	Plan a bounded prune of stale non-ready Python environment cache entries.
`python_environment_prune`	`soma:write`	`write`	MCP + CLI + REST	`POST /v1/python/environments/prune`	`soma python_environment_prune --json '{\`	`stale_before_unix_seconds` (required integer), (optional integer), (required boolean)

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:

Policy	When	Effect
Loopback development	Loopback bind, or `SOMA_MCP_NO_AUTH=true` on loopback	No auth middleware, no scope checks.
Bearer token	`SOMA_MCP_TOKEN` set	`/mcp` and `/v1/*` require `Authorization: Bearer <token>`.
OAuth	`SOMA_MCP_AUTH_MODE=oauth` with at least one configured provider	Browser-based Google, Authelia, or GitHub login issues JWT bearer tokens.
Trusted gateway	`SOMA_NOAUTH=true` on non-loopback	Local auth and scope checks disabled because an upstream gateway is responsible.

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.

Variable	Required	Default	Description
`SOMA_API_URL`	no	empty	Deployed platform API or upstream service URL. Empty selects stub/offline behavior.
`SOMA_API_KEY`	no	empty	Bearer token or upstream service API key.
`SOMA_PROVIDER_DIR`	no	`providers`	Directory scanned for drop-in provider files. Relative paths resolve from the current working directory.
`SOMA_MCP_HOST`	no	`127.0.0.1`	HTTP server bind host.
`SOMA_MCP_PORT`	no	`40060`	HTTP server bind port.
`SOMA_MCP_SERVER_NAME`	no	`soma`	MCP server name advertised to clients.
`SOMA_MCP_NO_AUTH`	no	`false`	Disable auth for loopback development.
`SOMA_NOAUTH`	no	`false`	Trusted-gateway non-loopback no-auth mode.
`SOMA_MCP_TOKEN`	bearer	empty	Static bearer token.
`SOMA_MCP_ALLOWED_HOSTS`	no	empty	Extra comma-separated Host header values.
`SOMA_MCP_ALLOWED_ORIGINS`	no	empty	Extra comma-separated CORS origins.
`SOMA_MCP_TRACE_HEADERS`	no	`off`	Trusted inbound HTTP trace extraction: `off`, `trusted`, or `trusted-with-baggage`.
`SOMA_MCP_AUTH_MODE`	no	`bearer`	`bearer` or `oauth`.
`SOMA_MCP_PUBLIC_URL`	OAuth	empty	Public URL for OAuth metadata and callbacks.

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

41 cargo members:

Path	Contents
`crates/soma/*`	Product code for this server — domain, application, config, client, api, cli, mcp, runtime, integrations, palette, web, test-support
`crates/shared/*`	Reusable engine crates other servers consume — auth, mcp (client/server/proxy/gateway), provider-core, provider-adapters, http-api, http-server, observability, openapi, self-update, traces, codemode, cli-core, and namespaced reusable families such as `cortex/ingest-core`
`crates/integrations/*`	Upstream service bridges — `gotify`, `unifi`
`apps/soma`	The `soma` binary and its integration tests. The only cargo member under `apps/` — `apps/web` (Next.js) and `apps/palette` (assets) are not Rust crates.
`packages/python`	pyo3 Python provider platform (`abi3-py311`)
`xtask`	All repository automation; `scripts/*.py` are thin wrappers over it

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:

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:

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.

Replace the stub client in crates/soma/client/src/client.rs only when the provider file path is not enough.
Put domain logic in crates/soma/application/src/service.rs or focused service modules.
Register native provider/action metadata so MCP, CLI, REST, docs, and plugins stay registry-driven.
Regenerate MCP schema docs, provider surface docs, and OpenAPI so generated surfaces reflect the provider registry.
Add REST handlers only for infrastructure routes; business actions should stay registry-backed direct routes.
Update config fields and env prefixes in crates/soma/config/src/config.rs.
Update .env.example, config.soma.toml, plugin options, and setup mappings.
Update server.json, plugin metadata, repository URLs, Docker labels, and release metadata.
Add tests for MCP dispatch, CLI parsing, REST routes, provider loading, and service behavior.
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

Topic	Docs
Architecture and layering	docs/ARCHITECTURE.md, docs/PATTERNS.md
Cortex shared-crate extraction	docs/cortex-extraction/README.md, ADR 0014
Dynamic provider runtime	docs/specs/dynamic-provider-runtime.md, docs/generated/provider-surfaces.md
Provider manifest contract	docs/contracts/provider-manifest.schema.json, docs/contracts/examples/provider-manifests
Scaffold workflow	docs/SCAFFOLD.md, docs/CARGO_GENERATE.md
Scaffold intent contract	docs/specs/scaffold-intent-handoff.md, docs/contracts/scaffold-intent.schema.json
MCP action schema	docs/MCP_SCHEMA.md
REST OpenAPI	docs/generated/openapi.json
Auth	docs/AUTH.md

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

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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Soma?

Does Soma need an API key?

What transport does Soma use?

When was Soma last checked?

Documentation

Soma

Contents

Naming

Capabilities And Boundaries

Batteries Included

Install

Product Profiles

Quickstart

Drop In A Provider

Scaffold A New Project

Architecture

Runtime Surfaces

MCP Tool Reference

CLI Reference

Safety And Trust Model

Authentication

Configuration

Development

Workspace layout

Client Configuration

Plugin Surfaces

Distribution Contract

Web UI

Deployment

When Drop-In Providers Are Not Enough

Troubleshooting

Related Servers

Documentation

Verification

License