Sovrant MCP server

Sovrant

A source-available command center for agents and agent activity — built on .NET 10.

Sovrant is a clean-room C# reimplementation inspired by the architecture and feature set of OpenClaude (the community fork of Anthropic's Claude Code). No Anthropic source code was copied, translated, or incorporated. Every line of Sovrant is original C# / .NET 10 code written from scratch — the project uses OpenClaude only as a functional reference for what an agentic coding tool should be able to do, not as a source of code.

We build Sovrant guided by four tenets:

1. Be ethical with AI — Sovrant is designed with safety, trust boundaries, and responsible use at its core. We believe AI systems should be transparent, auditable, and operate within clearly defined human-controlled limits.
2. Drive AI spend toward zero — by first-class support for free-tier and locally-hosted LLMs, Sovrant aims to make powerful AI accessible without recurring API costs. Paying for inference should be a choice, not a requirement.
3. Minimise compute footprint — every architectural decision considers CPU, memory, and energy efficiency. Lower resource consumption means a smaller environmental impact and better performance on modest hardware.
4. Own your own data — individuals, teams, and organisations should have full control over their data. Sovrant supports private workspaces, per-user memory scoping, and self-hosted LLMs so sensitive work never has to leave your infrastructure. Data privacy is a first-class feature, not an afterthought.

Sovrant is a command center for AI — from conversational chat and directed agents to persistent teams, long-running workflows, and parallel swarms. Runs can be fully autonomous, human-watched, or anywhere in between. Sovrant also connects to Claws — fully autonomous agent runtimes such as Pico Claw, Hermes, and Open Claw — via MCP, letting you observe and steer them from a single cockpit; future releases will let you launch Claws directly from Sovrant to handle tasks. It is not limited to coding — Sovrant powers chat interfaces, research workflows, business process automation, content creation, project management, and any task that benefits from tool-augmented, session-persistent AI.

The engine runs as a CLI agent, an OpenAI-compatible HTTP server, a desktop application (Windows/macOS/Linux), a web application (Blazor Server), an MCP server for IDE embedding, or via webhooks from Slack, Teams, Discord, and custom systems. Agents read and write files, execute shell commands, search the web, call tools autonomously, delegate to sub-agents, and maintain full conversation history across sessions — all with configurable permission controls.

Architecture note: The CLI, Server, Desktop, and Web are independent frontends. All consume the runtime layer (Sovrant.Runtime) directly — the server does not depend on the CLI, and the desktop/web apps run the runtime in-process. You can deploy any frontend independently.

Runtime: .NET 10 / C# 14 License: Business Source License 1.1 — source-available, converts to Apache 2.0 on 2029-05-15. See LICENSE. Status: 60 tools. 25 agent templates. 32 built-in skills. 138 HTTP endpoints + SignalR hub. Conversation folders. Command Center cockpit + User Dashboard (Web + Desktop). Per-record privacy toggles. Optional Supabase/PostgreSQL backend. Multi-user with login, registration, per-user API tokens, workspaces, projects, and ownership scoping. Team orchestration with per-team run profiles. Swarm orchestrator. Workflow engine with background scheduler. Inter-agent coordination. Cost tracking. Eval framework. MCP server mode. Desktop app. Web app (embedded + remote mode). Frontend SDK. 2,627 tests across 12 projects.

Web	Desktop

---

Table of Contents

• Quick Start
  • Vibe Coding (Cursor, Claude Code)
• Command Center
• User Dashboard
• Key Features
• Architecture
• Tools
• Agent System
• Workflows
• Eval Framework
• Providers
• Server API
• Desktop App
• Web App
• Frontend SDK
• MCP Server Mode
• LSP Integration
• Persistence
• Configuration
• Production Deployment
• Tests
• Documentation

---

Quick Start

Best experiences today: The Desktop app and the embedded Web app deliver the most complete, polished experience. The CLI is functional but actively being refined — treat it as a work in progress.

Vibe Coding (Cursor, Claude Code, or any AI coding tool)

The fastest way to get up and running is to let your AI coding tool do it for you. This has been proven to work with Cursor and Claude Code — paste the prompt below into your tool and it will clone the repo, orient itself, build the project, and launch both the Desktop and Web apps.

Clone https://github.com/ramseur/sovrant.git, then:
1. Read README.md for an overview of the project
2. Read every file in the docs/ folder to understand the architecture
3. Run: dotnet restore && dotnet build
4. Start the Desktop app (Windows — no console window):
   Start-Process dotnet -ArgumentList "run --project src/Sovrant.Desktop" -WindowStyle Hidden
   macOS/Linux: dotnet run --project src/Sovrant.Desktop &
5. Start the Web app: dotnet run --project src/Sovrant.Web
   (opens on http://localhost:5100)
Report what you find and confirm both surfaces are running.

Your tool will read the docs, build the solution, and start both surfaces. On first launch the Desktop setup wizard walks you through adding an API key — the Web app does the same on first login.

Prerequisites

• .NET 10 SDK or Runtime
• An API key from any supported LLM provider

Clone & Build

git clone https://github.com/ramseur/sovrant.git
cd sovrant
dotnet restore
dotnet build

Desktop App (recommended for first-time users)

The fastest way to get started. Full GUI with provider setup wizard, chat, and management pages.

Windows (PowerShell — no console window alongside the app):

Start-Process dotnet -ArgumentList "run --project src/Sovrant.Desktop" -WindowStyle Hidden

macOS / Linux:

dotnet run --project src/Sovrant.Desktop &

dotnet run uses WinExe output type so the app itself never shows a console window. The Start-Process -WindowStyle Hidden / & hides the dotnet host process. Alternatively, build first (dotnet build -c Release src/Sovrant.Desktop) and run the compiled executable directly — it launches with no console window on all platforms.

On first launch, the setup wizard guides you through provider configuration (API key, model selection). Supports OpenAI, OpenRouter, DeepSeek, Groq, Mistral, Together AI, Google, Azure OpenAI, Ollama, and LM Studio.

Web App

Browser-based UI on port 5100 with the full runtime embedded.

Pre-release — multi-user Web is new in 2.1.0. Embedded Web (the default) now signs in each browser separately, so a team can share one Web server: everyone sees only their own conversations and approvals and picks from the models their admins configured (Phase 145, GitHub #32). Load-tested with 1,000 people connected to one 4-core server — see Sizing Sovrant.Web. Remote mode (Web in front of Sovrant.Server, SOVRANT_RUNTIME_MODE=remote) is still single-user — Phase 146. See Running Web for a team.

dotnet run --project src/Sovrant.Web
# Open http://localhost:5100

CLI

Set your provider credentials. Sovrant stores API keys in an encrypted, on-disk credential store; the auth subcommand prompts without echo so the key never lands in shell history.

Recommended (interactive — no echo):

dotnet run --project src/Sovrant.Cli -- auth set llm
# Enter value for llm: ********

# inspect what's configured (names only, never values)
dotnet run --project src/Sovrant.Cli -- auth list

# remove a stored key
dotnet run --project src/Sovrant.Cli -- auth delete llm

Scripted / CI (read from stdin):

cat key.txt | dotnet run --project src/Sovrant.Cli -- auth set llm --stdin

From the environment (12-factor / containers / CI): set the key in the shell, the container's env, or a .env file. On first boot it's imported into the encrypted keystore, and a provider is set up for you; after that the stored value wins, so changes made in the UI stick. Set SOVRANT_ENV_OVERRIDE=true to re-apply env values on every start.

Linux / macOS / WSL:

export LLM_API_KEY="sk-..."
# Optional: use a different provider
export LLM_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"

Windows (PowerShell):

$env:LLM_API_KEY = "sk-..."
$env:LLM_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"

Precedence: environment variable > encrypted credential store > built-in default. auth list shows which is currently winning for each name.

Supported auth set <name> values: llm, provider, brave, firecrawl, openrouter.

Then run:

# One-shot prompt
dotnet run --project src/Sovrant.Cli -- --model gpt-4o-mini prompt "List all .cs files in src/"

# Interactive REPL
dotnet run --project src/Sovrant.Cli -- --model gpt-4o-mini

# Resume a named session
dotnet run --project src/Sovrant.Cli -- --model gpt-4o-mini --session my-project

# CI mode — machine-readable JSON output, non-zero exit on error
dotnet run --project src/Sovrant.Cli -- --ci --model gpt-4o-mini prompt "Fix the failing tests"

Server

dotnet run --project src/Sovrant.Server

The server starts on port 5200. On first run, register your admin account — the first user to register is automatically granted the admin role.

# 1. Register (first user becomes admin)
curl -X POST http://localhost:5200/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"your-password"}'
# → { "token": "svt_...", "user_id": "...", "role": "admin" }

# 2. Save your token
export SVT_TOKEN="svt_..."

All credentials (API keys, provider tokens) are stored in the AES-256-GCM encrypted keystore at ~/.sovrant/credentials/ by default. Environment variables (e.g. LLM_API_KEY, from the shell, container env or .env) are imported into it on first boot — or on every start with SOVRANT_ENV_OVERRIDE=true — for 12-factor / CI deployments and always take precedence over the stored value.

# Non-streaming
curl -X POST http://localhost:5200/v1/chat/completions \
  -H "Authorization: Bearer $SVT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

# Streaming (SSE)
curl -X POST http://localhost:5200/v1/chat/completions \
  -H "Authorization: Bearer $SVT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}],"stream":true}'

# Persistent session
curl -X POST http://localhost:5200/v1/chat/completions \
  -H "Authorization: Bearer $SVT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"My name is Alex"}],"session_id":"user-123"}'

Auth model: All requests require a svt_* bearer token. Log in via POST /v1/auth/login to get a token. Additional long-lived tokens can be issued via POST /v1/users/me/tokens (self-service) or POST /v1/users/{id}/tokens (admin). Tokens carry an optional expiry and can be revoked at any time. Non-admin callers see only their own data. See Multi-User & Workspaces.

Permission Modes

Mode	Behaviour
default	Asks before each tool use
acceptEdits	Auto-approves file edits, asks for shell
bypassPermissions	Auto-approves everything
dontAsk	Never prompts; silently skips denied tools
plan	Read-only — no file or shell writes

dotnet run --project src/Sovrant.Cli -- --permission-mode bypassPermissions prompt "Refactor the auth module"

Use camelCase for --permission-mode values: bypassPermissions, not bypass-permissions.

---

Command Center

The Command Center (/command) is the homepage for Web and Desktop — a single live grid that answers "what is Sovrant doing for me right now?" It aggregates every active workflow, team run, agent run, and conversation session into one read-only cockpit, with click-through to the existing detail pages (Activity, Orchestration, Workflows).

┌──────────────────────────────────────────────────────────────────────┐
│ Command Center                                           ⟳ live · 30s │
├──────────────────────────────────────────────────────────────────────┤
│ KIND       TITLE                       STATUS    STARTED   COST       │
│ 🎯 workflow Refactor the auth module   Running   12m ago   $0.42      │
│ 👥 team    Code review sweep           Running   3m ago    $0.08      │
│ 🤖 agent   security-auditor:OWASP scan Running   <1m ago   $0.01      │
│ 💬 session user-123                    Idle      2h ago    $1.17      │
└──────────────────────────────────────────────────────────────────────┘

• Live — polled every 30 seconds; paginated grid with header timestamp and page-preserve on navigation.
• Read-only by design (v1). Click a row to drill into the detail page that already exists for it.
• Privacy masking. Private records appear as masked rows — title and content are hidden, existence is acknowledged for admin accountability.
• Backed by one endpoint: GET /v1/command-center/state aggregates from agent_runs, the workflow engine, team_runs, and the session pool.
• First-run lands here. A clean install completes the setup wizard and lands the user on Command Center, not on a blank chat — the empty state explains how to start activity.

See docs/server.md for the endpoint contract and docs/frontend-integration.md for the SDK call.

---

User Dashboard

The User Dashboard (/dashboard) is a personal cross-workspace activity view, distinct from the Command Center. Reached via the 👤 rail nav icon on both Web and Desktop.

┌──────────────────────────────────────────────────────────────────────┐
│ My Activity                                              ⟳ live · 30s │
├──────────────────────────────────────────────────────────────────────┤
│ Shared (12)  Private (3)  Active (2)                                  │
├──────────────────────────────────────────────────────────────────────┤
│ KIND       TITLE                       PRIVACY   STARTED   WORKSPACE  │
│ 💬 session API research                 Public   2h ago    my-project │
│ 💬 session Internal notes              🔒 Private  1h ago  personal  │
│ 🤖 agent   doc-writer run              Public   3h ago    team-ws    │
└──────────────────────────────────────────────────────────────────────┘

• What you see: own public ("Shared") records + own private records + teammates' public records in shared workspaces. Other users' private records are never returned — not masked, not counted.
• Privacy toggles. Any session or agent run can be marked private. Private records are visible only to the owner. On the Command Center they appear as masked rows (title/content hidden); on the User Dashboard they're excluded entirely from other users' views. Server-side enforcement — no client-side bypass.
• Backed by GET /v1/user-dashboard/state. Powered by UserDashboardAggregator with workspace membership gating.

See docs/server.md for the endpoint contract.

---

Key Features

Provider-Agnostic LLM Routing

Connect to any OpenAI-compatible API — OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Mistral, Together AI, Ollama (local), LM Studio (local), Azure OpenAI, or any provider that speaks the OpenAI chat completions format. The SmartRouter pings all configured providers on startup, scores them by latency, cost, and error rate, and routes each request to the optimal one. Switch providers by changing an environment variable or from the desktop/web settings UI — no code changes.

Intent-Aware Model Routing

Automatically selects the best model for each turn based on what you're asking. A rule-based IntentClassifier categorizes every input into one of 10 intent classes (SimpleQa, CodeGeneration, Refactor, Planning, Debugging, etc.) with a complexity score (0.0–1.0), then routes to the appropriate model tier (fast / standard / high). The ModelTierResolver auto-assigns your discovered models into tiers from OpenRouter pricing data — no manual configuration needed.

Free models only mode — set SOVRANT_FREE_MODELS_ONLY=true to restrict routing to zero-cost models. On OpenRouter this means only :free variants are eligible; local/self-hosted models (Ollama) are always included.

Tool-aware routing — when the request includes tools, the resolver automatically filters to models that support native tool use, preventing 404 errors from providers that don't support tool_calls.

Configure via the Settings UI (Web + Desktop, persists to the DB) or environment variables — .sovrant/routing.json is no longer read as of Phase 93; any pre-existing file is imported once on first boot via LegacyConfigMigrator:

# Use OpenRouter as the provider
export LLM_BASE_URL="https://openrouter.ai/api/v1"
export LLM_API_KEY="sk-or-v1-..."
export OPENROUTER_API_KEY="sk-or-v1-..."  # enables live model discovery
export SOVRANT_MODEL="google/gemma-4-31b-it:free"

# Restrict to free models only (no charges)
export SOVRANT_FREE_MODELS_ONLY=true

# Inspect tier assignments
sovrant router models
sovrant router status

60 Built-in Tools

Agents autonomously use tools for file operations, shell execution, web access, task management, plan/worktree mode, notebook editing, MCP resource access, LSP code intelligence, code verification, skill execution, agent delegation, team orchestration, swarm orchestration, workflow management, artifact retrieval, and document generation. Up to 20 tool rounds per turn with automatic retries.

25 Specialized Agent Templates

Define reusable agent roles as .md files with YAML frontmatter — each specifying a name, recommended model tier, system prompt, and allowed tools. 25 built-in templates ship with the engine. Drop custom templates into .sovrant/agents/ to override built-ins or add your own.

32 Built-in Skills (Composable Workflow Packages)

Skills are single .md files — YAML frontmatter (name, trigger, agents, tools) plus a markdown body with steps and instructions. 32 built-in skills across 7 domains: research (5), writing (5), business (5), project management (4), coding (7), media (3), and agent infrastructure (3). Invoke via /trigger slash commands or programmatically. Create new skills at runtime with SkillCreate.

Team Orchestration

Create persistent named agents with specific roles, custom system prompts, and tool restrictions. Teams persist to SQLite across restarts with full workspace/project scoping. Manage teams from within the agentic loop (LLM tool calls), via the HTTP API (/v1/teams/*, /v1/runs/*), or from the desktop/web UI. Run teams with optional parallelism and file-level locking. Publish swarm workers as reusable team members.

Swarm Orchestrator

Submit a single complex prompt and the swarm auto-decomposes it into a task DAG, executes tasks in parallel waves via specialized agents, enforces file-level locking and token budgets, and runs an optional quality gate review. Available via CLI (sovrant swarm "task"), the Swarm tool, /swarm slash command, and POST /v1/swarm (SSE streaming).

Workflow Engine

Long-lived, goal-driven AI workflows that span multiple engine runs (formerly called "missions"). Describe a goal; the planner decomposes it into steps, agents execute them with re-planning and acceptance gates, and every transition lands in an event journal. Optionally review and edit the generated plan before it runs. Workflows are durable (persisted to SQLite), workspace-scoped, advanced in the background by WorkflowSchedulerService on the server, and manageable from the Workflows page (Web + Desktop) or the API (/v1/workflows/*). See Workflows.

Conversation Folders

File any conversation — plain chats, agent chats, workflow chats, webhook conversations, and the chats that launched a swarm or team run — into folders you create. Folders are per user, span every workspace, and nest up to 5 levels. Drag a conversation (or a folder) onto a folder, or use Move to folder… from its ⋯ menu or the chat header's Move button; invalid moves (a folder into its own subfolder, past 5 levels, a duplicate name) are refused while you drag. Deleting a folder moves its contents up a level — no conversation is ever deleted. Each row shows labels derived from what the conversation is linked to right now (Agent · researcher, Workflow · Running, Swarm · 2 runs, Webhook · slack); nothing about a conversation's type is stored. Web + Desktop parity; API at /v1/session-folders. See docs/server.md.

Session Persistence

Every conversation is stored in a SQLite database with full-text search via FTS5. Resume sessions by name across CLI invocations or HTTP requests. Automatic context compaction when conversations exceed token limits. See Persistence.