Connecting

The Soria backend must be running before you connect. Start it with make run-dev — the server listens on http://localhost:8900 by default.

MCP proxy (recommended)
Direct HTTP

The MCP proxy is a stdio server that runs locally and forwards requests to any Soria backend. It adds two built-in tools — environment_list and environment_switch — so you can point your AI assistant at a different environment without restarting Claude.

Add the proxy to your Claude config

To make the proxy available in every Claude Code session, add it to your global config at ~/.claude.json:

~/.claude.json

{
  "mcpServers": {
    "soria": {
      "command": "uv",
      "args": ["--directory", "/path/to/soria", "run", "python", "-m", "soria.mcp_proxy"]
    }
  }
}

Replace /path/to/soria with the absolute path to your local clone of the Soria repository.

Or use the project .mcp.json

If you’re working inside the Soria repository, the proxy config is already included in .mcp.json at the project root. Claude Code picks this up automatically when you open the repo:

.mcp.json

{
  "mcpServers": {
    "soria": {
      "command": "uv",
      "args": ["run", "python", "-m", "soria.mcp_proxy"]
    }
  }
}

List available environments

Once connected, run environment_list to see which backends are reachable:

Current: https://soria.example.com/mcp/

  local [OFFLINE]: http://localhost:8900/mcp
  prod [available]: https://soria.example.com/mcp/ (active)
  streaming-extraction [available]: https://soria-streaming-extraction.example.com/mcp/

Local servers are discovered automatically. Deployed production and any active PR preview environments appear alongside them.

Switch to a backend

Run environment_switch to connect to a different environment. The tool list updates immediately — no restart needed.

Value	Connects to
`local`	`http://localhost:8900/mcp/`
`local:PORT`	`http://localhost:PORT/mcp/`
`prod`	Deployed production environment
`streaming-extraction`	PR preview environment named `streaming-extraction`
Full URL	Any Soria backend at that URL

Example:

environment_switch("local")
→ Switched from https://soria.example.com/mcp/ to http://localhost:8900/mcp/

You can connect directly to a specific Soria backend without running the proxy. This is simpler to set up, but you need to reconnect if you want to switch environments.

Connect to a local backend

claude mcp add --transport http soria http://localhost:8900/mcp/

Or connect to a deployed instance

Replace the URL with your deployment’s address:

claude mcp add --transport http soria https://your-deployment-url/mcp/

Direct HTTP connections do not include environment_list or environment_switch. To change backends, remove the server with claude mcp remove soria and add it again with the new URL.

Overview

Ingestion Tools

Pipeline Tools

Warehouse & Models

Intelligence Tools