Universal MCP Hub: AIRIS MCP Gateway

The observability-first gateway for all your MCP tools. Connect once, evaluate everywhere.

---

🛠️ Quick Install & Universal Setup

1. Start the Gateway

curl -fsSL https://raw.githubusercontent.com/agiletec-inc/airis-mcp-gateway/main/install.sh | bash

Development Setup

# 1. Copy and fill in your API keys
cp .env.example .env

# 2. Start the gateway
docker compose up -d

# 3. View logs
docker compose logs -f api

Tip: For secure secret management, use Doppler instead of .env:

doppler setup                              # One-time setup
doppler run -- docker compose up -d        # Injects secrets at runtime

2. Connect Your AI Client

Register the gateway once, and access all backend MCP servers (Stripe, Supabase, GitHub, etc.) through a single connection.

Client	Connection Command / Setup
Codex	codex mcp add airis-mcp-gateway --url http://localhost:9400/mcp
Claude Code	Plugin: /install-plugin agiletec-inc/airis-mcp-gateway
Gemini CLI	gemini mcp add --transport sse airis-mcp-gateway http://localhost:9400/sse
Cursor	Settings > Features > MCP > Add New MCP Server Name: airis-mcp-gateway, Type: SSE, URL: http://localhost:9400/sse
Windsurf	Add SSE URL http://localhost:9400/sse to ~/.codeium/config.json

Docker Compose publishes the API on port 9400. Codex uses Streamable HTTP at http://localhost:9400/mcp, and SSE clients such as Gemini CLI should use http://localhost:9400/sse. Claude Code connects via the plugin system (includes MCP connection, permissions, hooks, and skills).

---

🧠 Why Universal MCP Hub?

1. Observability-First (Moving beyond "Vibes")

Stop guessing if your toolset is actually helping. Airis tracks and visualizes real performance, providing the same observability found in platforms like Codex (OTel ready):

• Token Efficiency: Measurable reduction in initial context overhead.
• Workflow Precision: Tracking Steps-to-Success (StS) for complex tasks.
• Latency & Reliability: Real-time monitoring of each MCP server's health, latency, and success rates.

2. Intelligent Noise Reduction

Even with large context windows, exposing 100+ tools simultaneously leads to "tool selection hallucinations." Airis keeps the initial capability surface small, activates toolsets on demand, and lets models call native tools directly once the right capability slice is exposed.

3. Single Source of Truth

No more repeating API keys and server configs across different projects or AI tools. Gateway server definitions live in one global registry, and the gateway runtime reads a single mcp-config.json.

Configuration Policy

AIRIS uses a single global registry at ~/.airis/mcp/registry.json.

• Repository-local mcp.json files are not supported.
• Existing mcp.json files should be imported into the global registry, backed up, and removed.
• airis-gateway init --apply also deploys AIRIS best-practice assets to Codex, Claude Code, and Gemini.
• Codex and Gemini can be managed automatically by AIRIS.
• Claude Desktop is detected, but its MCP config is not modified automatically.

Use:

airis-gateway init ~/github
airis-gateway init ~/github --apply
airis-gateway doctor ~/github

AIRIS Best Practices

AIRIS is not only a central MCP registry. It also distributes operating guidance for when to use MCP, CLI, skills, and hooks.

• Check docs before implementing unfamiliar libraries or APIs.
• Use MCP for shared external capabilities with structured I/O.
• Prefer CLI for deterministic local workflows such as git, gh, docker, pytest, and Playwright.
• Prefer Playwright CLI over Playwright MCP for normal browser testing because it is faster and more token-efficient.
• Use skills and hooks for workflow guidance, guardrails, and repeatable team conventions.

How It Works

Airis aggregates 20+ MCP servers behind a single SSE endpoint. Your AI agent connects once and gets access to everything.

Without Gateway:                          With Gateway:
  claude mcp add stripe ...                 claude mcp add airis ...
  claude mcp add supabase ...               # Done. 100+ tools available.
  claude mcp add tavily ...                 # Shared across Gemini, Cursor, etc.
  ... Manage 20 servers individually ...

Servers start on-demand when a tool is called and auto-terminate when idle. No resources wasted.

Architecture

Claude / Gemini / Cursor / Windsurf
    │
    ▼ SSE (Unified Interface)
┌─────────────────────────────────────────────────────────┐
│  AIRIS MCP Gateway (The Intelligent Hub)                │
│                                                         │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────┐ │
│  │ Intelligent      │  │ Lifecycle        │  │ Auth & │ │
│  │ Routing (Find)   │  │ Manager (On-Demand)│  │ Secrets│ │
│  └──────────────────┘  └──────────────────┘  └────────┘ │
│            │                    │                 │     │
└────────────┼────────────────────┼─────────────────┼─────┘
             ▼                    ▼                 ▼
      [ uvx / npx ]        [ Docker MCP ]    [ Remote SSE ]
    Stripe, Supabase,     Mindbase, Tavily,   Custom APIs
    GitHub, etc.          etc.

See ARCHITECTURE.md for the full system design.

Available Servers

Enabled (start on-demand)

Server	Description
context7	Library documentation lookup
memory	Knowledge graph (entities, relations)
tavily	Web search via Tavily API
supabase	Supabase database management
stripe	Stripe payments API
fetch	Web page fetching as markdown
sequential-thinking	Step-by-step reasoning
serena	Semantic code retrieval and editing
magic	UI component generation
morphllm	Code editing with warpgrep
chrome-devtools	Chrome debugging

Disabled (auto-enable when called)

Server	Description
twilio	Twilio voice/SMS API
cloudflare	Cloudflare management
github	GitHub API
postgres	Direct PostgreSQL access
filesystem	File system operations
git	Git operations
time	Time utilities

All servers start on first tool call and auto-terminate when idle. Disabled servers are automatically enabled when you call their tools — no manual setup needed.

Documentation

• Dynamic MCP deep-dive — Architecture, cache behavior, auto-enable flow
• Target architecture — Toolset-centric AIRIS direction and design boundaries
• Toolset roadmap — Phased implementation plan for capability slices
• Capability selection guide — When to use MCP vs skills vs hooks vs subagents vs CLI
• Configuration reference — Environment variables, TTL settings, server config
• Gateway vs Plugins — When to use Gateway vs Claude Code plugins
• Deployment guide — Production setup, API auth, monitoring, reverse proxy
• Architecture — System design and component responsibilities
• Contributing — Development setup, Devbox, go-task, PR guidelines

License

MIT