Irigate

Documentation

Getting Started

Install Irigate, validate a profile, start the broker, and connect one selected client.

This path installs and starts a loopback-only broker, then connects one client with the narrowest recommended selector.

Requirements

  • Python 3.11 through 3.14.
  • uv for installation and execution.
  • Node.js with npx for the Context7 upstream in profiles/mvp.yaml.
  • An installed code-review-graph executable if you select the isolated code-review-graph upstream.

The default profile starts no upstream process until an agent selects one. First selected use may download upstream package artifacts and require network access.

Installation

Install the published PyPI release as an isolated user application:

uv tool install irigate
irigate --version

Ensure uv’s tool bin directory—normally ~/.local/bin—is on PATH; run uv tool update-shell if needed. For a virtual-environment installation, use python3 -m venv ~/.venvs/irigate followed by ~/.venvs/irigate/bin/python -m pip install irigate.

Development installation

Use an editable installation when developing or debugging Irigate:

uv tool install --editable .

Source edits take effect the next time you invoke irigate; no reinstall is needed. To exercise a release-like snapshot of the current checkout instead, run:

uv tool install --force --from . irigate

The snapshot stays frozen at the current source state until you reinstall. Confirm either installation from the repository root:

irigate --help
irigate --config profiles/mvp.yaml --check

Tool installation does not install test dependencies into the checkout. Create the locked project environment before running tests or repository commands:

uv sync --frozen
uv run --frozen irigate --config profiles/mvp.yaml --check

Minimal profile

The smallest useful profile has a profile name, an upstreams map, and each upstream’s command plus required idle timeout:

name: local-development
upstreams:
  context7:
    command: npx
    args: ["-y", "@upstash/context7-mcp"]
    idle_timeout_seconds: 300

Save it as a YAML file such as profiles/local.yaml.

Validate without starting upstreams

Run:

irigate --config profiles/local.yaml --check

Validation rejects unknown fields, duplicate YAML keys, unsupported transports, invalid routing keys, non-loopback listeners, and missing environment references before any upstream starts.

Start the broker

Run:

irigate --config profiles/mvp.yaml --require-qualified-sharing

The broker listens at http://127.0.0.1:8765/mcp. Stop it with Ctrl+C; shutdown drains active calls and closes child processes.

Connect one client

Prefer exact tool selection for least privilege:

http://127.0.0.1:8765/mcp?tools=context7__resolve-library-id,context7__query-docs

This URL connects to the already-running profile and exposes only those namespaced tools. It does not repeat the profile’s name or upstreams fields as query parameters.

Read Configuration for profile fields and reload behavior, then Agent selection for exact tool and upstream selector semantics.