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.
