airis-mcp-gateway

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.