Skip to main content

Connect · Claude Code

Use SignalPilot in Claude Code

Claude Code is the client SignalPilot supports most fully. One command connects the governed data tools, and the plugin adds skills that guide dbt and SQL work plus verifier agents that check the result.

You need a SignalPilot account with at least one database connected, and Claude Code installed on your machine. Setup takes a couple of minutes.

  1. Create an API key

    Open SignalPilot, go to Settings → API Keys, and choose Create new key. Name it after where it will live, such as claude-code-laptop, and keep the default read and query permissions.

    The key starts with sp_ and is shown once. Copy it now. If you lose it, delete it and create another.

  2. Add the server

    Run this in a terminal, replacing the placeholder with your key:

    add signalpilot to claude code
    $ claude mcp add --transport http signalpilot https://gateway.signalpilot.ai/mcp \
      --header "x-api-key: sp_your_key_here"

    By default the server is added for the current project only. Add --scope user to make it available in every project on your machine.

    If you would rather not type this, Settings → MCP Connect in SignalPilot generates the exact command for your workspace.

  3. Check the connection

    Start a Claude Code session and type:

    check mcp servers
    /mcp

    You should see signalpilot with the status connected and a list of tools. You can also just ask:

    List the MCP tools available from SignalPilot.

    Claude should name tools such as query_database, list_tables, and dbt_error_parser.

  4. Install the plugin

    The plugin is what turns a set of tools into a workflow. It adds skills (guides Claude follows for dbt and SQL tasks) and verifier agents (checks that run after a build).

    install the plugin
    $ claude plugin marketplace add SignalPilot-Labs/signalpilot-plugin
    $ claude plugin install signalpilot-dbt@signalpilot

    Restart Claude Code after installing. The plugin overview explains what each skill and agent does.

  5. Ask your first question

    Ask something you already know the answer to:

    How many orders shipped last week?

    Claude calls SignalPilot, SignalPilot runs a governed read-only query, and the answer comes back with the SQL it used. Checking a known number first is the fastest way to confirm everything works.

Self-hosted gateway​

If you run SignalPilot yourself, point Claude Code at your own gateway instead:

add a self-hosted gateway
$ claude mcp add --transport http signalpilot http://localhost:3300/mcp

A fresh self-hosted gateway accepts MCP requests without a key until the first API key is created. After that, add the same --header "x-api-key: sp_your_key_here" flag as the cloud command. See API keys and permissions for the self-hosted details.

If something does not work​

What you seeWhat to do
/mcp shows signalpilot as failedCheck the URL is exactly https://gateway.signalpilot.ai/mcp with no trailing slash, then remove and re-add: claude mcp remove signalpilot followed by the add command above.
"Authentication required" or "Unauthorized"The header must be x-api-key and the value must be the full key including sp_. If you are not sure the key is still valid, create a new one.
The server connects but tools are missingQuit and reopen Claude Code so it reconnects. claude mcp list shows what is registered.
Skills do not loadConfirm the plugin is installed with claude plugin list, then restart Claude Code.
Self-hosted: server unreachableOpen http://localhost:3300/health in a browser. If it does not answer, the gateway is not running. Note the port is 3300, not 8081 (an old default).
Claude answers but the numbers look wrongAdd the missing business definition to the knowledge base and ask again.

Next​