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