AIRIS MCP Gateway

When performing tasks, use the following routing map to select the appropriate tool or capability:

To ensure system stability and security, the following invariants must be respected during development or integration:

• Routing: Do not route the gateway to anything other than exact library/framework documentation.
• Error Handling: Do not implement silent fallbacks for disabled or missing servers.
• Transport Integrity: The transport bridge must not prematurely close SSE (Server-Sent Events) iterators.
• Security Boundaries: Do not centralize external write capabilities or provider credentials within the gateway.
• Observability: Metrics and status reports should not be treated as a substitute for enforcement mechanisms.

The AIRIS MCP Gateway manages the lifecycle of local Streamable HTTP/SSE endpoints and Context7 subprocesses.

Key Architectural Principles:

• Session Model: Clients do not register globally. Instead, they create short-lived sessions from a skill.
• Data Flow: agent skill -> localhost:9400/mcp -> transport bridge -> Context7 process.
• Isolation: The gateway is designed to be isolated. External resources such as provider-native agents, credential stores, browsers, Git, filesystem, memory, and general web search reside outside the gateway.
• Security/Containerization: Do not mount sensitive directories like ~/.codex or ~/.claude into the gateway container.

The AIRIS MCP Gateway is a local MCP endpoint designed to provide Context7 only when necessary. It is not intended to be registered as a global MCP that is always active.

Operational Model:

• Standard Tasks: Handled by native tools or specific skills (e.g., File, Git, GitHub, Web Search, Browser operations, External Write).
• Official Library/Framework Documentation: Handled by calling the airis-mcp-gateway skill, which then invokes Context7.

Security/Deployment Note: Do not mount the provider credential directory into the container.

The AIRIS workflow mandates a research-first approach before modifying any codebase. When performing tasks, follow these rules to ensure implementation accuracy:

1. Summarize Implementation: Always summarize the existing implementation of the target area before attempting edits.
2. Documentation Lookup: If a task involves a specific library or API, use AIRIS documentation lookup tools before changing any code.
3. Browser Testing: For browser-based testing tasks, prioritize using the Playwright CLI instead of MCP tools.
4. Pre-implementation Readiness: Do not proceed to the implementation phase until you can explicitly identify:
   • The target files involved.
   • The public interfaces being interacted with.
   • The specific acceptance checks required for the task.

This service is designed to run exclusively on a local machine and should not be exposed to the public internet. It does not include a production reverse proxy, TLS, or a public hostname.

Preconditions

Before starting, ensure you have the following:

• A Docker-compatible container runtime installed.
• Port 9400 available on localhost.
• A local registry created from the config/mcp-config.template.json file.

Start the service

Use devbox and task to bring up the environment:

devbox shell
task dev:up
curl -fsS http://localhost:9400/health

For end-user installations, use the root install.sh script.

Follow these steps to record a demo of the project for use in assets:

1. Open your terminal in the project's root directory.
2. Start your recording software (Kap or CleanShot X) and select only the terminal window.
3. Execute the demo script:

   ./scripts/demo-for-gif.sh

4. Wait for the terminal to display "Done!", then stop the recording.
5. Export the recording as a GIF with a width of 720px and a frame rate of 15fps.
6. Save the final file as assets/demo.gif.

When deciding how to execute a task within the AIRIS ecosystem, follow this routing order to select the appropriate tool or interface:

1. Identify the task type: Determine if it is a shared external capability, a local deterministic workflow, or workflow guidance.
2. Use MCP (Model Context Protocol): Select MCP for shared APIs and tasks requiring structured I/O.
3. Use CLI: Select the CLI for deterministic local execution (e.g., Playwright, git, docker, or test runners).
4. Use hooks or skills: Select these when the requirement is for guardrails or reusable workflow steps.

Always provide a brief explanation of the chosen route before proceeding with the work.

Developers can set up the environment by cloning the repository and using devbox and task to bring up the services. After starting, you can verify the installation by checking the health endpoint.

Steps:

1. Clone the repository.
2. Enter the directory.
3. Initialize the development shell with devbox shell.
4. Start the services with task dev:up.
5. Verify with a curl request to the health endpoint.

git clone https://github.com/agiletec-inc/airis-mcp-gateway.git
cd airis-mcp-gateway
devbox shell
task dev:up
curl -fsS http://localhost:9400/health

To install the AIRIS MCP Gateway as a user, run the provided installation script via curl. This will set up the local MCP endpoint.

Note: During installation, a runtime registry is created from config/mcp-config.template.json. The file mcp-config.json.example is a minimal empty template and does not represent the current list of active servers. Do not commit your local mcp-config.json to version control.

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

To create high-quality GIFs for project assets, install a screen recording tool like Kap or CleanShot X. For Kap, use Homebrew:

brew install --cask kap

To ensure the best visual quality, configure your terminal with these settings:

• Background: Black
• Text Color: Green or white
• Font Size: 14-16pt
• Window Size: Approximately 1280x720