### Docker Compose Setup for Gateway

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Quick start guide for local development using Docker Compose. Includes steps for environment setup, starting the gateway, viewing logs, and connecting AI clients.

```bash
# 1. Copy environment file and add API keys
cp .env.example .env

# 2. Start the gateway
docker compose up -d

# 3. View logs
docker compose logs -f api

# 4. Connect Claude Code
claude mcp add --transport http --scope user airis-gateway http://localhost:9400/mcp/

# 5. Connect Cursor (SSE)
# Settings > Features > MCP > Add New MCP Server
# Name: airis-mcp-gateway, Type: SSE, URL: http://localhost:9400/sse
```

--------------------------------

### Install Autostart Task

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Create a macOS LaunchAgent or Linux systemd user unit for automatic startup on boot.

```bash
task autostart:install
```

--------------------------------

### Check Autostart Status

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Verify that the autostart task has been successfully installed and is running.

```bash
task autostart:status
```

--------------------------------

### Clone and Configure AIRIS MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/DEPLOYMENT.md

Clone the repository, navigate to the directory, and copy the example configuration file. Set production environment variables for CORS origins and API key generation. Start the gateway using Docker Compose.

```bash
git clone https://github.com/agiletec/airis-mcp-gateway.git
cd airis-mcp-gateway
cp mcp-config.json.example mcp-config.json

export ALLOWED_ORIGINS=https://your-app.com
export AIRIS_API_KEY=$(openssl rand -hex 32)

docker compose up -d

./scripts/airis-gateway init

claude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse
```

--------------------------------

### Install Kap Screen Recorder

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/assets/README.md

Use Homebrew to install the Kap screen recording application. This is a free tool for capturing terminal sessions.

```bash
brew install --cask kap
```

--------------------------------

### Start Development Environment with Docker Compose

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Manually starts the development environment using Docker Compose if Devbox is not used. Includes a health check.

```bash
# Manual alternative (you manage your own tool versions)
docker compose up -d
curl http://localhost:9400/health
```

--------------------------------

### Configure Python MCP Server

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Example JSON configuration for enabling and running a Python MCP server using 'uvx'.

```json
{
  "my-server": {
    "command": "uvx",
    "args": ["my-mcp-server"],
    "enabled": true,
    "mode": "cold"
  }
}
```

--------------------------------

### Install Devbox

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Installs Devbox for a reproducible development environment. Ensure you have curl installed.

```bash
curl -fsSL https://get.jetify.com/devbox | bash
```

--------------------------------

### Recommended Setup: Plugins and MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/gateway-vs-plugins.md

This tree structure illustrates the recommended organization of host-dependent plugins and Docker-isolated MCP Gateway services.

```tree
Plugins (host-dependent):     MCP Gateway (Docker-isolated):
├── claude-api (files)        ├── context7 (HOT)
├── superpowers (workflow)    ├── tavily (cold)
└── playwright-cli (browser)  ├── supabase (cold)
                              ├── stripe (cold)
                              ├── cloudflare (cold)
                              └── ... (20+ more, zero cost when cold)
```

--------------------------------

### Install AIRIS MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Installs the AIRIS MCP Gateway using a curl script. This is the quickest way to get started.

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

--------------------------------

### Configure Node.js MCP Server

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Example JSON configuration for enabling and running a Node.js MCP server using 'npx'.

```json
{
  "my-server": {
    "command": "npx",
    "args": ["-y", "@org/my-mcp-server"],
    "enabled": true,
    "mode": "cold"
  }
}
```

--------------------------------

### Toolset Activation Example

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/dynamic-mcp.md

Activation in Dynamic MCP occurs at the toolset level, such as 'stripe.customers' or 'supabase.sql'. After activation, the provider may be cold-started, the capability slice becomes visible, and native tools become directly callable.

```text
- `stripe.customers`
- `stripe.billing`
- `supabase.sql`
- `supabase.auth`
```

--------------------------------

### Normal Request Flow Example

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/dynamic-mcp.md

Illustrates the normal request flow in Dynamic MCP: activate capability, refresh visible tools, and then call the native MCP tool directly. This avoids the overhead of a meta-tool.

```text
User: create a Stripe customer

LLM: airis-activate toolset="stripe.customers"
AIRIS: tools/list_changed
LLM: stripe:create_customer { ... }
```

--------------------------------

### Deploy AIRIS Gateway in Full Mode

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/ARCHITECTURE.md

Command to start all AIRIS services as Docker containers using Docker Compose with the 'full' profile.

```bash
docker compose -f infra/compose.yaml --profile full up -d
```

--------------------------------

### Development Setup for AIRIS MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Sets up the AIRIS MCP Gateway for development using Docker Compose. Remember to copy and fill in your API keys into the .env file.

```bash
# 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
```

--------------------------------

### Deploy AIRIS Gateway in Lite Mode

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/ARCHITECTURE.md

Command to start the AIRIS gateway and process-based MCP servers using Docker Compose in the default lite mode.

```bash
docker compose up -d
```

--------------------------------

### Development Workflow with Hot Reload

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Starts the development environment with hot reload enabled for Python and Node.js, and watches for TypeScript changes.

```bash
devbox shell              # Enter dev environment
task dev:up               # Start with hot reload
task docker:logs          # Watch for changes
```

--------------------------------

### Control Tools for Dynamic MCP

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/dynamic-mcp.md

Recommended control tools for the Dynamic MCP include 'airis-activate' for activating toolsets, 'airis-schema' for getting tool schemas, and 'airis-find' as an optional fallback search.

```text
`airis-activate` | Activate a toolset or provider slice
```

```text
`airis-schema` | Get schema for a native tool when needed
```

```text
`airis-find` | Optional fallback search across tool and server metadata
```

--------------------------------

### Example Toolset Catalog Structure

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/toolset-roadmap.md

This JSON structure defines a toolset catalog, mapping providers to their available capabilities (toolsets and individual tools). It is intended to be human-editable and checked into the repository.

```json
{
  "stripe": {
    "toolsets": {
      "customers": ["create_customer", "update_customer", "list_customers"],
      "payments": ["create_payment_intent", "capture_payment_intent"],
      "billing": ["create_invoice", "finalize_invoice", "pay_invoice"]
    }
  }
}
```

--------------------------------

### Revert to Legacy Mode in AgileTec Airis MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

To expose all tools directly, set the DYNAMIC_MCP environment variable to 'false' before starting the gateway.

```bash
DYNAMIC_MCP=false docker compose up -d
```

--------------------------------

### Get Dashboard Summary

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Returns aggregated summary data for dashboards and tray applications. This endpoint provides a high-level overview of the system's state.

```bash
curl "http://localhost:9400/api/v1/dashboard/summary"
```

--------------------------------

### Troubleshoot Server Startup with 'airis-find'

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Use 'airis-find' with a query if you are unsure about the required provider or toolset for server startup issues.

```bash
airis-find query="your_task"
```

--------------------------------

### Enter Devbox Shell and List Tasks

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Enters the reproducible development environment provided by Devbox and lists all available go-task commands.

```bash
devbox shell              # Enter dev environment (or use direnv)
task --list-all           # Show all available tasks
```

--------------------------------

### Verify Airis MCP Gateway Installation and Health

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Check the health endpoint of the gateway and retrieve counts and status of registered tools and servers.

```bash
# Check health
curl http://localhost:9400/health
```

```bash
# List all tools
curl http://localhost:9400/api/tools/combined | jq '.tools_count'
```

```bash
# Check server status
curl http://localhost:9400/api/tools/status | jq '.servers[] | {name, status}'
```

--------------------------------

### Run Demo Script for GIF

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/assets/README.md

Execute the provided shell script to generate the demo output for the GIF recording. Ensure you are in the project directory.

```bash
./scripts/demo-for-gif.sh
```

--------------------------------

### Import and Clean Repositories

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/DEPLOYMENT.md

Commands to import existing repositories, apply configurations, clean up local MCP files, and run a health check on repositories. Use these when migrating existing projects.

```bash
./scripts/airis-gateway import ~/github --apply
./scripts/airis-gateway clean ~/github
./scripts/airis-gateway doctor ~/github
```

--------------------------------

### Command Line Comparison: Without vs. With Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Illustrates the difference in command-line usage for adding MCP servers when not using the Airis Gateway versus when using it. The Gateway simplifies server management by providing access to a large number of tools through a single command.

```bash
Without Gateway:
  claude mcp add stripe ... 
  claude mcp add supabase ... 
  claude mcp add tavily ... 
  ... Manage 20 servers individually ...

With Gateway:
  claude mcp add airis ... 
  # Done. 100+ tools available.
  # Shared across Gemini, Cursor, etc.
```

--------------------------------

### Retrieve Tool Schema with airis-schema

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Use this to get the full input schema for a specific tool before calling it. Ensure the tool name is correctly specified in the arguments.

```bash
curl -X POST "http://localhost:9400/api/v1/mcp/sse?sessionid=ABC123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "airis-schema",
      "arguments": {
        "tool": "memory:create_entities"
      }
    }
  }'
```

--------------------------------

### Import Repo-Local MCP Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Import existing repository-local 'mcp.json' definitions into the global registry and apply them.

```bash
airis-gateway import ~/github --apply
```

--------------------------------

### Get Gateway Status

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Returns the current status of the MCP Gateway, indicating whether it is running or stopped. Provides details about the gateway's operational status.

```bash
curl "http://localhost:9400/api/v1/gateway/status"
```

--------------------------------

### Common go-task Commands

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Provides a list of frequently used go-task commands for managing the Docker stack, logs, and running tests.

```bash
task docker:up            # Start the stack
task docker:down          # Stop the stack
task docker:logs          # Follow API logs
task docker:restart       # Restart API container
task test:e2e             # Run end-to-end tests
task status               # Quick health check
```

--------------------------------

### Route Tools with airis-exec

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Use 'airis-exec' to route tasks to specific tools based on their function. For example, use 'tavily-search' for external information or 'stripe:*' for payment processing.

```bash
airis-exec context7:resolve-library-id
```

```bash
airis-exec context7:query-docs
```

```bash
airis-exec tavily:tavily-search
```

```bash
airis-exec supabase:query
```

```bash
airis-exec stripe:*
```

```bash
airis-exec cloudflare:*
```

```bash
airis-exec figma:*
```

--------------------------------

### Check Gateway Runtime Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Inspect the gateway's runtime configuration to verify MCP server settings.

```bash
# Check gateway runtime config
cat ~/.local/share/airis-mcp-gateway/mcp-config.json | jq '.mcpServers | keys'
```

--------------------------------

### Initialize AIRIS Gateway Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Commands to initialize and apply AIRIS gateway configuration for a specified directory. This also deploys best-practice assets.

```bash
airis-gateway init ~/github
airis-gateway init ~/github --apply
```

--------------------------------

### MCP Gateway vs Claude Code Plugins: Tool Comparison

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/gateway-vs-plugins.md

This table lists tools and explains why they are better suited as plugins.

```markdown
| Tool | Why Plugin |
|------|-----------|
| `playwright-cli` | Needs host Chrome browser — can't run inside Docker |
| `superpowers` | Workflow skills (TDD, debugging, planning) — no MCP equivalent |
| `claude-api` | File generation (docx/xlsx/pptx/pdf) — host filesystem access needed |
```

--------------------------------

### List of Tools

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/dynamic-mcp.md

Traditional MCP exposes all tools directly, leading to a large tool list that bloats the model context. This is particularly problematic for providers with many unrelated tools.

```text
tools/list → 60+ tools × full descriptions and schemas
```

--------------------------------

### Manage MCP Server Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Add new MCP servers to 'mcp-config.json'. Migrate from repo-local 'mcp.json' using 'airis-gateway import' and 'airis-gateway clean'.

```bash
airis-gateway import <dir> --apply
```

```bash
airis-gateway clean <dir>
```

--------------------------------

### Clean Repo-Local MCP Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Create a backup of repository-local 'mcp.json' files before deleting them after import.

```bash
airis-gateway clean ~/github
```

--------------------------------

### Expand Tool Schema or Documentation with expandSchema

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Lazy-loads full schemas or documentation for a specific tool. Use mode="schema" for JSON schema or mode="docs" for description text. This reduces initial token overhead.

```bash
curl -X POST "http://localhost:9400/api/v1/mcp/sse?sessionid=ABC123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "expandSchema",
      "arguments": {
        "toolName": "stripe_create_invoice",
        "mode": "schema"
      }
    }
  }'
```

--------------------------------

### Compile Behavior Instructions

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Execute a Python script within the API container to compile and display server behavior instructions based on the loaded MCP configuration.

```bash
docker compose exec api python -c "from app.core.behavior_compiler import compile_instructions; from app.core.mcp_config_loader import load_mcp_config; print(compile_instructions(load_mcp_config().servers))"
```

--------------------------------

### Schema Partitioning for Token Optimization

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/ARCHITECTURE.md

Illustrates how schema partitioning must occur at the proxy layer (Gateway) to optimize tokens by intercepting requests before they reach MCP servers.

```text
Claude Code
    ↓ tools/list request
Gateway ← Must intercept HERE to reduce tokens
    ↓
MCP servers (return full schemas)
```

--------------------------------

### MCP Configuration File Structure

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Configure MCP servers in `mcp-config.json`. Settings include mode (hot/cold), timeouts, and environment variables for server commands.

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "enabled": true,
      "mode": "hot",
      "idle_timeout": 900,
      "min_ttl": 300,
      "max_ttl": 3600,
      "description": "Knowledge graph (entities, relations)"
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}"],
      "enabled": true,
      "mode": "cold",
      "idle_timeout": 120,
      "description": "Web search via Tavily API",
      "tools_index": [
        {"name": "tavily_search", "description": "Search the web"},
        {"name": "tavily_extract", "description": "Extract content from URL"}
      ]
    },
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all", "--api-key=${STRIPE_SECRET_KEY}"],
      "enabled": false,
      "mode": "cold",
      "description": "Stripe payments API"
    }
  }
}
```

--------------------------------

### Follow API Logs

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Use this command to continuously monitor the logs generated by the API service.

```bash
task docker:logs
```

--------------------------------

### Initialize Global MCP Registry

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Initialize the global MCP registry at '~/.airis/mcp/registry.json' for your GitHub repositories.

```bash
airis-gateway init ~/github
```

--------------------------------

### Create New MCP Server

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Registers a new MCP server with the gateway. Supports both uvx (Python) and npx (Node.js) based servers. Environment variables can be configured using `${VAR_NAME}` syntax.

```bash
curl -X POST "http://localhost:9400/api/v1/mcp/servers/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-custom-server",
    "enabled": true,
    "command": "npx",
    "args": ["-y", "@org/my-mcp-server"],
    "env": {"API_KEY": "${MY_API_KEY}"},
    "description": "My custom MCP server",
    "category": "custom"
  }'
```

```json
# Response (201 Created):
# {
#   "id": 3,
#   "name": "my-custom-server",
#   "enabled": true,
#   "command": "npx",
#   "args": ["-y", "@org/my-mcp-server"],
#   "env": {"API_KEY": "${MY_API_KEY}"},
#   "description": "My custom MCP server",
#   "category": "custom",
#   "created_at": "2024-01-15T12:00:00Z",
#   "updated_at": "2024-01-15T12:00:00Z"
# }
```

--------------------------------

### Using Doppler for Secret Management

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Demonstrates how to use Doppler for secure secret management with Docker Compose for the AIRIS MCP Gateway.

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

--------------------------------

### Check Gateway Metrics

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Fetch and display metrics from the gateway, useful for monitoring performance and identifying issues.

```bash
curl http://localhost:9400/metrics
```

--------------------------------

### List All Server States

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Returns the current runtime states for all MCP servers, including whether they are enabled. Useful for monitoring server health and status.

```bash
curl "http://localhost:9400/api/v1/server-states/"
```

--------------------------------

### Dynamic MCP - airis-exec Tool Call

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Executes a tool from any server using the 'airis-exec' tool. This auto-enables COLD servers on demand. Requires a session ID and specifies the tool and its arguments.

```bash
curl -X POST "http://localhost:9400/api/v1/mcp/sse?sessionid=ABC123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "airis-exec",
      "arguments": {
        "tool": "memory:create_entities",
        "arguments": {
          "entities": [
            {"name": "AIRIS", "entityType": "Project", "observations": ["MCP Gateway"]}
          ]
        }
      }
    }
  }'
```

--------------------------------

### Process Server Issues

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Check the status of specific servers, like memory usage, and view relevant logs.

```bash
# Check specific server status
curl http://localhost:9400/process/servers/memory | jq
```

```bash
# View server logs
docker compose logs api | grep -i memory
```

--------------------------------

### List Process Servers

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Retrieve a list of all servers currently being managed or processed by the gateway.

```bash
curl http://localhost:9400/process/servers
```

--------------------------------

### Check and Adjust Rate Limits

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Monitor current rate limits by checking metrics and increase them by setting an environment variable before restarting services.

```bash
# Check current limits
curl http://localhost:9400/metrics | grep rate
```

```bash
# Increase limits (see DEPLOYMENT.md for details)
export RATE_LIMIT_PER_IP=200
docker compose up -d
```

--------------------------------

### Verify Repository Local Drift

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Check for any remaining repository-local drift after initialization or import processes.

```bash
# Verify there is no repo-local drift left behind
airis-gateway doctor ~/github
```

--------------------------------

### Update Tool Usage for Dynamic MCP

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

When using tools directly, activate the toolset first using 'airis-activate' before calling the tool. This is a change from the previous direct calling method.

```python
# Old
result = mcp.call("memory:create_entities", {...})

# New
mcp.call("airis-activate", {"toolset": "memory.core"})
result = mcp.call("memory:create_entities", {...})
```

--------------------------------

### MCP Gateway vs Claude Code Plugins: Service Comparison

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/gateway-vs-plugins.md

This table outlines services and their suitability for MCP plugins or the Gateway, indicating the preferred choice.

```markdown
| Service | Plugin | Gateway | Winner |
|---------|--------|---------|--------|
| Supabase | MCP plugin | `supabase` (cold) | **Gateway** — Docker-isolated, one config |
| Stripe | MCP plugin | `stripe` (cold) | **Gateway** — same reason |
| GitHub | MCP plugin | `github` (cold) | **Gateway** — or just use `gh` CLI |
| Slack | MCP plugin | Add to config | **Gateway** — when needed |
| Context7 | MCP plugin | `context7` (hot) | **Gateway** — 700 tokens, negligible overhead |
| Playwright | MCP plugin | ~~`playwright`~~ | **Neither** — use `playwright-cli` skill (host Chrome, no Docker needed) |
```

--------------------------------

### Rebuild MCP Servers with go-task

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CONTRIBUTING.md

Rebuilds the MCP servers using go-task. Use `dev:watch` for automatic rebuilding on file changes.

```bash
task build:mcp            # Rebuild MCP servers
# Or use watch mode:
task dev:watch            # Auto-rebuild on file changes
```

--------------------------------

### Import and Clean Repository Data

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/troubleshooting.md

Apply repository data imports and clean up any leftover migration input files.

```bash
airis-gateway import ~/github --apply
```

```bash
airis-gateway clean ~/github
```

```bash
airis-gateway doctor ~/github
```

--------------------------------

### Activate Toolset for 'Tool not found' Error

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

If you encounter a 'Tool not found' error, activate the relevant toolset first using 'airis-activate'.

```bash
airis-activate toolset="provider.slice"
```

--------------------------------

### MCP Servers - Create Server

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

Registers a new MCP server with the gateway, supporting both Docker-based and process-based servers.

```APIDOC
## MCP Servers - Create Server

### Description
Registers a new MCP server in the gateway. Supports uvx (Python) and npx (Node.js) based servers.

### Method
POST

### Endpoint
`/api/v1/mcp/servers/`

### Headers
- **Content-Type**: application/json

### Request Body
- **name** (string) - Required - Name of the new MCP server.
- **enabled** (boolean) - Optional - Whether the server should be enabled upon creation (defaults to true).
- **command** (string) - Required - The command to start the server (e.g., "npx", "uvx").
- **args** (array of strings) - Optional - Arguments for the server command.
- **env** (object) - Optional - Environment variables for the server. Use `${VAR_NAME}` for secrets.
- **description** (string) - Optional - A description for the server.
- **category** (string) - Optional - The category the server belongs to.

### Request Example
```json
{
  "name": "my-custom-server",
  "enabled": true,
  "command": "npx",
  "args": ["-y", "@org/my-mcp-server"],
  "env": {"API_KEY": "${MY_API_KEY}"},
  "description": "My custom MCP server",
  "category": "custom"
}
```

### Response
#### Success Response (201 Created)
- The newly created MCP server object.
  - **id** (integer) - Unique identifier for the server.
  - **name** (string) - Name of the server.
  - **enabled** (boolean) - Whether the server is enabled.
  - **command** (string) - The command to start the server.
  - **args** (array of strings) - Arguments for the server command.
  - **env** (object) - Environment variables for the server.
  - **description** (string) - Description of the server.
  - **category** (string) - Category of the server.
  - **created_at** (string) - Timestamp of creation.
  - **updated_at** (string) - Timestamp of last update.

#### Response Example
```json
{
  "id": 3,
  "name": "my-custom-server",
  "enabled": true,
  "command": "npx",
  "args": ["-y", "@org/my-mcp-server"],
  "env": {"API_KEY": "${MY_API_KEY}"},
  "description": "My custom MCP server",
  "category": "custom",
  "created_at": "2024-01-15T12:00:00Z",
  "updated_at": "2024-01-15T12:00:00Z"
}
```
```

--------------------------------

### Verify MCP Configuration Integrity

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Run 'airis-gateway doctor' to check for any remaining repository-local 'mcp.json' files after migration.

```bash
airis-gateway doctor ~/github
```

--------------------------------

### Create Custom Claude Code Commands

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/claude-code-commands.md

Add a markdown file to the `.claude/commands/` directory to create custom commands. Specify the command's description and allowed tools in the frontmatter. The prompt for the command goes in the main body, using $ARGUMENTS for user input.

```markdown
# .claude/commands/my-command.md
---
description: What this command does
allowed-tools: Bash(docker*), mcp__airis-mcp-gateway__*
---

Your prompt here. Use $ARGUMENTS for user input.
```

--------------------------------

### Initialize and Apply AIRIS Gateway Assets

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/configuration.md

Use these commands to initialize the AIRIS gateway and apply best-practice assets to Codex, Claude Code, and Gemini. The `doctor` command checks for any remaining repository-local mcp.json files.

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

--------------------------------

### Run Gateway Health Tests with /test

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/claude-code-commands.md

Use the `/test` command in Claude Code for an end-to-end test of gateway health, tools, and pre-warming. For a full test including data persistence across restarts, use `/test persistence`.

```bash
# In Claude Code TUI, just type:
/test                    # Run full test suite
/status                  # Quick health check
/troubleshoot timeout    # Debug timeout issues
```

--------------------------------

### Manage Rate Limiting

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/DEPLOYMENT.md

View current rate limit metrics and increase limits by setting the RATE_LIMIT_PER_IP environment variable and restarting the services.

```bash
# Check current limits
curl http://localhost:9400/metrics | grep rate
```

```bash
# Increase limits
export RATE_LIMIT_PER_IP=200
docker compose up -d
```

--------------------------------

### Take Snapshot with Playwright CLI

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/CLAUDE.md

Generate a snapshot (image) of the current browser state after opening a URL with the Playwright CLI. This is a token-efficient alternative to full screenshots.

```bash
playwright-cli snapshot
```

--------------------------------

### Configure Windsurf for AIRIS MCP Gateway

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/README.md

Instructions for configuring Windsurf to connect to the AIRIS MCP Gateway by adding the SSE URL to the Codeium configuration file.

```json
Add SSE URL `http://localhost:9400/sse` to `~/.codeium/config.json`
```

--------------------------------

### Dynamic MCP - Tool Execution

Source: https://context7.com/agiletec-inc/airis-mcp-gateway/llms.txt

APIs for dynamic tool execution via the MCP gateway using JSON-RPC over SSE.

```APIDOC
## Dynamic MCP - airis-find Tool

Searches for available tools and servers. Used for tool discovery without loading all schemas.

### Method
POST

### Endpoint
/api/v1/mcp/sse?sessionid={sessionid}

### Parameters
#### Query Parameters
- **sessionid** (string) - Required - The session ID for the SSE connection.

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, should be "2.0".
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - Parameters for the method.
  - **name** (string) - Required - The name of the tool to call (e.g., "airis-find").
  - **arguments** (object) - Required - Arguments for the tool.
    - **query** (string) - Required - The search query.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airis-find",
    "arguments": {
      "query": "memory"
    }
  }
}
```

### Response via SSE
- **event** (string) - The event type, typically "message".
- **data** (object) - The JSON-RPC response.
  - **jsonrpc** (string) - JSON-RPC version.
  - **id** (integer) - The request ID.
  - **result** (object) - The result of the tool call.
    - **content** (array) - The content of the result.
      - **type** (string) - The type of content (e.g., "text").
      - **text** (string) - The textual representation of the result.

### Response Example
```
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Found 4 tools across 1 servers\n\n## Servers\n- **memory** (hot, enabled): 4 tools\n\n## Tools\n- **memory:create_entities** - Create new entities in the knowledge graph\n- **memory:search_nodes** - Search for nodes in the graph\n..."}]}}
```

## Dynamic MCP - airis-exec Tool

Executes a tool from any server without pre-activation. Auto-enables COLD servers on demand.

### Method
POST

### Endpoint
/api/v1/mcp/sse?sessionid={sessionid}

### Parameters
#### Query Parameters
- **sessionid** (string) - Required - The session ID for the SSE connection.

#### Request Body
- **jsonrpc** (string) - Required - JSON-RPC version, should be "2.0".
- **id** (integer) - Required - The request ID.
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - Parameters for the method.
  - **name** (string) - Required - The name of the tool to call (e.g., "airis-exec").
  - **arguments** (object) - Required - Arguments for the tool.
    - **tool** (string) - Required - The full name of the tool to execute (e.g., "memory:create_entities").
    - **arguments** (object) - Required - Arguments for the specific tool being executed.
      - **entities** (array) - Example argument for `create_entities` tool.
        - **name** (string) - Required - The name of the entity.
        - **entityType** (string) - Required - The type of the entity.
        - **observations** (array) - Optional - Observations about the entity.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airis-exec",
    "arguments": {
      "tool": "memory:create_entities",
      "arguments": {
        "entities": [
          {
            "name": "AIRIS",
            "entityType": "Project",
            "observations": ["MCP Gateway"]
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Check MCP Server Configuration

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/DEPLOYMENT.md

Use this command to inspect the keys within the 'mcpServers' section of your mcp-config.json file. Restart the API after making configuration changes.

```bash
# Check mcp-config.json
cat mcp-config.json | jq '.mcpServers | keys'
```

```bash
# Restart after config changes
docker compose restart api
```

--------------------------------

### Optional Fallback Tool Search in Dynamic MCP

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Use 'airis-find' as an optional fallback search mechanism when the exact tool or toolset is unclear.

```python
# Optional fallback search
mcp.call("airis-find", {"query": "memory"})
```

--------------------------------

### Activate Specific Toolset in Dynamic MCP

Source: https://github.com/agiletec-inc/airis-mcp-gateway/blob/main/docs/MIGRATION.md

Directly activate a known capability slice using 'airis-activate' when you know the specific toolset required.

```python
mcp.call("airis-activate", {"toolset": "stripe.customers"})
```