Quick Start

The fastest way to use Soria is through the MCP server, which lets Claude Code call all Soria tools directly. Follow these steps to connect and run your first commands.

Add the MCP proxy to Claude Code

The MCP proxy is a stdio server that connects Claude Code to any Soria backend. Add it to your global Claude Code config at ~/.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 Soria repository. Alternatively, the project’s .mcp.json (already in the repo root) configures this automatically when you open the project in Claude Code.

Start the backend

The MCP server runs as part of the Soria backend. Start it with:

make run-dev

The backend starts on http://localhost:8900. The MCP endpoint is at http://localhost:8900/mcp/.

Discover available environments

Once connected in Claude Code, ask it to call environment_list to see available backends:

Use environment_list to show me available Soria environments

This returns all reachable environments — your local server, any deployed instances, and PR preview environments.

Switch to your environment

Use environment_switch to connect to a specific backend without restarting Claude Code:

Use environment_switch to connect to local

You can also switch to a deployed environment by name (e.g., soria-streaming-extraction) or a full URL.

Try your first commands

Explore what’s available:

List all dashboard pages

Search for Medicare Advantage enrollment data

Show me the available data scrapers

To start building a pipeline, create a workspace first — all write operations require one:

Create a workspace for a new scraper called my_data_source

Direct HTTP connection (alternative)

If you prefer to connect directly to a specific backend without the proxy:

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

Replace the URL with your deployment URL to connect to a remote instance. Note that direct connections don’t support environment switching — you’ll need to reconnect to change backends.

What’s next

MCP Overview

Browse all available MCP tools by category

Pipeline Overview

Learn how the data ingestion pipeline works

Workspaces

Understand workspace isolation before making data changes

Dashboards

Explore and query your data

Get Started

Data Pipeline

Workspaces

Dashboards

News Intelligence

Direct HTTP connection (alternative)

What’s next

MCP Overview

Pipeline Overview

Workspaces

Dashboards

​Direct HTTP connection (alternative)

​What’s next

MCP Overview

Pipeline Overview

Workspaces

Dashboards

Direct HTTP connection (alternative)

What’s next