Skip to main content

System overview

Architecture diagram​

architecture
┌─────────────────────────────────────────────────────────────┐
│  Your AI Agent (Claude, ChatGPT, Claude Code, any MCP client)│
└────────────────────────────┬────────────────────────────────┘
                             │ MCP Protocol (streamable-http)
┌────────────────────────────▼────────────────────────────────┐
│  SignalPilot Gateway                                         │
│  ┌────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│  │ Governance │ │ Schema       │ │ dbt Project           │ │
│  │ • LIMIT    │ │ • DDL        │ │ • Map / Validate      │ │
│  │ • DDL block│ │ • Explore    │ │ • Model verification  │ │
│  │ • Audit    │ │ • Join paths │ │ • Date boundaries     │ │
│  └────────────┘ └──────────────┘ └───────────────────────┘ │
└────────────────────────────┬────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐        ┌──────────┐        ┌──────────┐
   │ DuckDB  │        │ Postgres │        │Snowflake │
   └─────────┘        └──────────┘        └──────────┘

In motion​

A natural-language ask flowing through Claude Code, MCP, and a governed query.
dbt project scan and schema discovery before a build.
dbt DAG and model lineage as the workflow expands.
Parse-time governance rejecting a DDL attempt.
Verifier-agent receipt after a successful build.

Components​

ComponentResponsibility
GatewayFastAPI backend. Exposes 62 MCP tools over streamable-http. Handles auth, rate limiting, SQL governance, query execution, and audit logging. Port 3300.
Chat workerSeparate process from the same image. Claims and runs chat and agent jobs.
Web UINext.js 16 frontend. Connections, chat, notebooks, query history, dashboards. Port 3200.
EngineSQL governance: AST parsing, DDL/DML blocking, dangerous function denial, LIMIT injection, dialect normalization.
Connectors12 database connectors with pooling and SSH tunneling: DuckDB, PostgreSQL, MySQL, SQLite, SQL Server, Snowflake, Databricks, BigQuery, Redshift, ClickHouse, Trino, and Xata.
AuthClerk JWT (cloud) or API key (local and cloud). Org-scoped with brute-force protection.
SandboxesPer-session isolated microVMs for notebooks and chat. Local mode uses one shared notebook container.
PluginClaude Code plugin: 24 skills and 2 verifier agents. Installed separately with claude plugin.
sp-sandboxSandbox manager for DuckDB and SQLite queries over local files.
CloudSignalPilot Cloud: hosted gateway with SSO, multi-tenant isolation, managed history.

Project structure​

project structure
signalpilot/
├── signalpilot/
│   ├── gateway/              # FastAPI backend: MCP server, REST API, governance
│   │   └── gateway/
│   │       ├── api/          # REST API modules
│   │       ├── connectors/   # 12 database connectors + pooling + SSH tunneling
│   │       ├── governance/   # Budget, cache, PII redaction, annotations
│   │       ├── mcp/          # 62 MCP tool definitions (modular package)
│   │       ├── engine/       # SQL validation, LIMIT injection, function denylist
│   │       ├── dbt/          # Project scanning, validation, hazard detection
│   │       ├── db/           # SQLAlchemy models, async engine, Alembic migrations
│   │       └── auth/         # Clerk JWT (cloud) / local auth + org role enforcement
│   ├── notebook-server/      # Notebook runtime that runs inside each sandbox
│   └── web/                  # Next.js 16 frontend
│       ├── app/              # App router pages (chat, connections, notebooks, etc.)
│       ├── components/       # UI components
│       └── lib/              # API client, auth context, hooks
├── signalpilot-plugin/       # Canonical agent plugin (24 skills, 2 verifier agents)
│   ├── agents/               # Structure and value verifier agents
│   └── skills/               # dbt workflow, SQL, domain, and reporting skills
├── sp-sandbox/               # DuckDB/SQLite sandbox manager
├── benchmark/                # Spider 2.0-DBT benchmark suite (SOTA: 51.56%)
└── docker-compose.yml        # Full local stack

Deployment modes​

Self-hosted (Docker Compose)​

self-hosted
$ docker compose up -d
# Web UI:   http://localhost:3200
# Gateway:  http://localhost:3300

One docker-compose.yml brings up the web UI, gateway, chat worker, notebook container, Postgres, MinIO object storage, a mail catcher, the sandbox manager, and a read-only object proxy for evals. Every port binds to loopback. Auth is API-key based. See Self-host with Docker Compose.

SignalPilot Cloud​

Multi-tenant. Clerk JWT for SSO. Org-scoped API keys. Managed history, dashboards, and encrypted credential storage. Notebooks and chat run in per-session isolated microVMs. See SignalPilot Cloud plans and the client guides for Claude, ChatGPT, and Claude Code.

MCP transport​

SignalPilot uses streamable-http, the current MCP standard. The endpoint is mounted at:

  • /mcp (canonical)
  • / (backward compatibility)

MCP tool calls are stateless per request. Your client keeps the session context; the gateway holds no open stream between tool calls.