Sovrant can run as an MCP (Model Context Protocol) server, allowing MCP-aware IDEs and agents to use it as a tool provider. Two transports are supported, both backed by the same handlers in the Sovrant.Mcp library:
| Transport | Entry point | Best for |
|---|---|---|
| stdio (JSON-RPC over stdin/stdout) | sovrant mcp-server subcommand |
Local IDE integration — IDE spawns Sovrant as a child process |
| HTTP/SSE | Sovrant.Server with SOVRANT_MCP_HTTP=true, exposed at /mcp |
Remote / multi-tenant access; reuses the server's bearer-token auth |
Both transports expose the same tools, resources, prompts, and completions.
Opt-in only — never runs unless explicitly launched:
export LLM_API_KEY="sk-..."
sovrant mcp-serverOr with dotnet run:
dotnet run --project src/Sovrant.Cli -- mcp-serverThe process blocks on stdin, waiting for JSON-RPC messages from the connected IDE. It exits when stdin closes (IDE disconnects).
No performance overhead: When not using mcp-server, no MCP services are registered, no code paths execute, and no resources are consumed.
Run Sovrant.Server (port 5200 by default) with SOVRANT_MCP_HTTP=true:
export SOVRANT_MCP_HTTP=true
dotnet run --project src/Sovrant.Server
# → MCP endpoint live at http://localhost:5200/mcpClients connect to http://<host>:<port>/mcp over HTTP/SSE and authenticate using a per-user svt_* bearer token (Authorization: Bearer svt_...) — the same auth used by every other Sovrant.Server endpoint. SOVRANT_MCP_TOKEN only applies to the stdio path. When SOVRANT_MCP_HTTP=false (the default), the /mcp endpoint is not registered.
Add to .vscode/settings.json:
{
"github.copilot.chat.mcpServers": {
"sovrant": {
"command": "dotnet",
"args": ["run", "--project", "path/to/src/Sovrant.Cli", "--", "mcp-server"],
"env": {
"LLM_API_KEY": "sk-..."
}
}
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"sovrant": {
"command": "dotnet",
"args": ["run", "--project", "path/to/src/Sovrant.Cli", "--", "mcp-server"],
"env": {
"LLM_API_KEY": "sk-..."
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"sovrant": {
"command": "dotnet",
"args": ["run", "--project", "path/to/src/Sovrant.Cli", "--", "mcp-server"],
"env": {
"LLM_API_KEY": "sk-..."
}
}
}
}Add to .claude/mcp.json:
{
"mcpServers": {
"sovrant": {
"command": "dotnet",
"args": ["run", "--project", "path/to/src/Sovrant.Cli", "--", "mcp-server"],
"env": {
"LLM_API_KEY": "sk-..."
}
}
}
}Tip: If you've published Sovrant as a single binary, replace
"dotnet", "run", "--project", "path/to/src/Sovrant.Cli", "--"with just"sovrant".
All tools registered in IToolRegistry are exposed via MCP, plus a synthetic chat tool.
All 60 standard tools are available:
File: Read, Write, Edit, Glob, Grep, LS
Shell: Bash, PowerShell, REPL
Web: WebFetch, WebSearch
Task Management: TodoWrite, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate
Agent & Interaction: Agent, AskUserQuestion, Sleep
Plan & Worktree: EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree
Team Orchestration: TeamCreate, TeamDelete, TeamStatus, TeamDelegate, TeamRun, TeamPublish
Workflows: Workflow
Swarm & Coordination: Swarm, SwarmStatus, CoordinationStatus
Discovery & Skills: ToolSearch, Skill, SkillCreate
Artifacts & Documents: Artifact, DocumentGenerate, DocumentFromTemplate, DocumentListTemplates, DocumentSuggestTemplate, DocumentPackage, DocumentListPackages
Code Scaffolding: CodeCreate, CodeCreateMulti, CodeListTemplates, CodeValidate
Quality: Verify
MCP: ListMcpResources, ReadMcpResource, MCPTool, McpAuth
LSP: LspHover, LspDefinition, LspReferences, LspDiagnostics, LspRename
Notebook: NotebookEdit
A synthetic MCP tool that runs a full Sovrant agentic turn — the IDE sends a message, Sovrant runs it through the LLM with the full tool loop, and returns the final response.
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Yes | The user message to send to the agentic loop |
session_id |
string | No | Session ID to resume a previous conversation |
The chat tool always passes the tool filter — it cannot be excluded.
| URI | Description | MIME Type |
|---|---|---|
sovrant://sessions |
List of all session IDs with at least one entry | application/json |
sovrant://config |
Current Sovrant runtime configuration | application/json |
sovrant://sessions/{id} |
Full message history for a specific session | application/json |
By default, all tools are exposed. Set SOVRANT_MCP_TOOLS to a comma-separated list to restrict which tools are available:
# Only expose file tools and chat
export SOVRANT_MCP_TOOLS="Read,Write,Edit,Glob,Grep,LS"
sovrant mcp-serverThe chat tool is always available regardless of the filter.
Tool names are case-sensitive — use the exact names as shown above.
Auth differs by transport:
- stdio: no HTTP, no
Authorizationheaders. The token is checked once as a startup gate — the process exits before accepting any JSON-RPC messages if the token is missing or wrong. Configured viaSOVRANT_MCP_TOKEN+--token. - HTTP/SSE: uses the standard
Sovrant.Serverbearer auth — clients sendAuthorization: Bearer svt_...(a per-user token) on every request.SOVRANT_MCP_TOKENis not consulted on this path.
Step 1 — set the required token on the server side:
export SOVRANT_MCP_TOKEN="your-secret-token"This is the token the server expects. Keep it secret (use a secrets manager, .env file with restricted permissions, or a system keychain).
Step 2 — pass the token in your IDE config via --token:
{
"command": "sovrant",
"args": ["mcp-server", "--token", "your-secret-token"],
"env": {
"LLM_API_KEY": "sk-..."
}
}Behavior:
SOVRANT_MCP_TOKEN |
--token provided |
Result |
|---|---|---|
| Not set | Any | Allowed (open mode) |
| Set | Not provided | Process exits, error to stderr |
| Set | Wrong value | Process exits, error to stderr |
| Set | Correct value | Allowed |
Errors go to stderr so they don't corrupt the stdout JSON-RPC transport. The IDE will see the process exit immediately with a non-zero code.
{
"github.copilot.chat.mcpServers": {
"sovrant": {
"command": "sovrant",
"args": ["mcp-server", "--token", "your-secret-token"],
"env": {
"LLM_API_KEY": "sk-..."
}
}
}
}| Variable | Required | Description |
|---|---|---|
LLM_API_KEY |
Yes | API key for the LLM provider |
LLM_BASE_URL |
No | Provider base URL (default: OpenAI) |
SOVRANT_MCP_TOKEN |
No | stdio only. Required bearer token. If set, callers must pass --token <value> matching this. Unset = no auth required. |
SOVRANT_MCP_HTTP |
No | HTTP/SSE only. Set to true on Sovrant.Server to enable the /mcp endpoint. Default: false. |
SOVRANT_MCP_TOOLS |
No | Comma-separated allow-list of tool names. Applies to both transports. Unset = all tools. |
All standard Sovrant environment variables (ROUTER_MODE, ROUTER_STRATEGY, SOVRANT_WEB_SEARCH, etc.) are respected.
- Token authentication — stdio uses
SOVRANT_MCP_TOKEN+--tokenas a startup gate; HTTP/SSE uses per-usersvt_*bearer tokens enforced bySovrant.Serverper request. - Permission mode is forced to
DontAskon the stdio path — all tool executions are auto-approved because there is no console to prompt. The HTTP path inherits the server's configured permission policy. - Console logging is suppressed (stdio only) — stdout is the JSON-RPC transport on stdio, so logs go to file only (
~/.sovrant/logs/). The HTTP path uses normal server logging. - Network exposure — stdio is only accessible to the parent process that spawned it. HTTP/SSE binds wherever
Sovrant.Serveris configured to listen; restrict access at the network or reverse-proxy layer if exposing beyond localhost. - Use
SOVRANT_MCP_TOOLSto restrict which tools are exposed if you want to limit what clients can do.
Some MCP servers require OAuth authorization before they can be used (e.g., GitHub MCP server requires a GitHub OAuth app token). Sovrant handles this through the McpAuth tool and a lightweight OAuth 2.0 Authorization Code + PKCE flow that runs through the Sovrant HTTP server.
Sovrant.Servermust be running on port 5200 (orSOVRANT_PORT)- The OAuth app's redirect URI must be registered as
http://localhost:{SOVRANT_PORT}/v1/mcp/auth/callback
Add oauth_config to an MCP server entry in settings.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"oauth_config": {
"client_id": "your-github-oauth-app-client-id",
"authorization_url": "https://github.com/login/oauth/authorize",
"token_url": "https://github.com/login/oauth/access_token",
"scopes": ["repo", "read:org"],
"token_env_var": "GITHUB_TOKEN",
"redirect_uri": "http://localhost:5200/v1/mcp/auth/callback"
}
}
}
}| Field | Required | Description |
|---|---|---|
client_id |
Yes | Your OAuth app's client ID |
client_secret |
No | Client secret (omit for public clients — PKCE is always used) |
authorization_url |
Yes | Provider's authorization endpoint |
token_url |
Yes | Provider's token endpoint |
scopes |
No | OAuth scopes to request |
token_env_var |
No | Env var to inject the access token into when reconnecting the MCP process |
redirect_uri |
No | Redirect URI override (default: http://localhost:{SOVRANT_PORT}/v1/mcp/auth/callback) |
- The model detects an MCP tool call fails with an auth error (or the user asks to authorize an MCP server).
- The model calls the
McpAuthtool with{ "server": "github" }. - Sovrant generates an authorization URL (PKCE challenge included) and returns it as text.
- The model surfaces the URL to the user: "Please visit this URL to authorize GitHub access: https://github.com/..."
- The user visits the URL, approves access in their browser.
- GitHub redirects to
http://localhost:5200/v1/mcp/auth/callback?code=...&state=... - Sovrant exchanges the code for an access token, stores it encrypted in
~/.sovrant/credentials/. - If
token_env_varis set, Sovrant reconnects the MCP server process with the token injected as that environment variable. - The user sees a success page and closes the tab — no further action needed.
Tokens are stored AES-256-GCM encrypted in ~/.sovrant/credentials/. The master encryption key lives in ~/.sovrant/credentials/.keystore (user-only permissions on POSIX). Tokens are never written to session history, logs, or any other file.
- PKCE (
code_challenge_method=S256) is always used, even when aclient_secretis present. - OAuth state parameters expire after 10 minutes — attempts to replay a callback after expiry are rejected.
- The
/v1/mcp/auth/callbackendpoint is exempt from bearer token authentication (the OAuth provider redirects there without credentials). The CSRFstateparameter is the security control. - The callback endpoint is only accessible if
Sovrant.Serveris running locally — it is not exposed to the internet.
The shared protocol library is Sovrant.Mcp — McpServerSetup.AddSovrantMcpHandlers() registers tools/list, tools/call, resources/list, resources/read, prompts, completions, logging, and resource subscriptions on whatever transport is hosting it. Tool calls are dispatched through IToolRegistry, the same registry used by the CLI and HTTP server — there is no separate tool implementation.
stdio path:
- The IDE starts
sovrant mcp-serveras a child process. - The CLI registers
Sovrant.Mcphandlers withWithStdioServerTransport(). - JSON-RPC requests arrive on stdin; responses are written to stdout.
HTTP/SSE path (SOVRANT_MCP_HTTP=true on Sovrant.Server):
Sovrant.Serverregisters the sameSovrant.Mcphandlers withWithHttpTransport()and maps them at/mcp.- Clients send JSON-RPC over HTTP/SSE, authenticating with
Authorization: Bearer svt_...(a per-user token).
The synthetic chat tool (available on both transports) creates a transient ConversationRuntime and runs a full agentic turn — the caller gets the agent's complete response including any tool use.