AIR MCP Server

Connect AI assistants to AIR (AI Responsibly) for governed risk assessments: discover projects, upload evidence, run assessments, and retrieve structured reports — from Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, or any Model Context Protocol client.

This package ships two transports:

Local assessment workloads still execute on Thalus cloud via the AIR Integrator API. You provide a domain-scoped API key for stdio; remote Directory clients authorize through the AIR portal (OAuth). No local database, worker, or Docker stack is required for stdio.

Overview

┌──────────────────────┐   stdio MCP   ┌──────────────────┐   HTTPS   ┌─────────────────┐
│  Your IDE / agent    │ ◄────────────► │  @thalus-ai/     │ ────────► │  AIR Integrator │
│  (Cursor, Claude,    │               │  mcp-air (local) │           │  API (cloud)    │
│   VS Code, …)        │               └──────────────────┘           └─────────────────┘
└──────────────────────┘

Related MCP server: Phantom MCP

Prerequisites

• Node.js 20+

• An AIR organization with active billing (assessments consume credits)

• A domain-scoped API key with scopes appropriate for your workflow (see API key scopes)

Quick start

1. Create an API key

In the AIR portal: open your domain → API Keys → create a key with the assessmentRunner or fullPipeline preset (see below).

2. Configure your MCP client

Add the server to whichever client you use. All clients run the same npx command; only the config file and JSON root key differ.

Most clients (Cursor, Claude Code, Claude Desktop, Windsurf) — mcpServers:

{
  "mcpServers": {
    "air": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thalus-ai/mcp-air@1.1.0"],
      "env": {
        "AIR_API_KEY": "${env:AIR_API_KEY}"
      }
    }
  }
}

VS Code — servers in .vscode/mcp.json (docs):

{
  "servers": {
    "air": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thalus-ai/mcp-air@1.1.0"],
      "env": {
        "AIR_API_KEY": "${env:AIR_API_KEY}"
      }
    }
  }
}

Set AIR_API_KEY in your shell, or use envFile where supported. See Client setup for file paths per IDE.

3. Verify

Ask your agent to run air_list_domains and air_list_projects. You should see successful tool calls in the MCP log.

MCP Inspector (optional):

AIR_API_KEY=your-key npx @modelcontextprotocol/inspector npx -y @thalus-ai/mcp-air@1.1.0

Remote HTTP (operators)

Hosted endpoint: https://mcp.air.thalus.ai/mcp.

# After build
AIR_API_URL=https://api.air.thalus.ai \
REDIS_URL=redis://127.0.0.1:6379 \
OAUTH_INTROSPECT_CLIENT_ID=your-resource-server-client-id \
OAUTH_INTROSPECT_CLIENT_SECRET=your-resource-server-client-secret \
MCP_HTTP_PORT=4104 \
node dist/build/http.mjs

Deploy notes, Angie, and systemd units live in infra/. Claude Directory users connect via OAuth on air.thalus.ai — see Remote MCP OAuth once published.

Configuration

You only need AIR_API_KEY. The server connects to production AIR automatically.

API key scopes

Choose a portal preset when creating your key:

Org-wide portfolio dashboards require a browser session in the portal and are not available via MCP.

Full scope reference: Authentication guide.

Client setup

Claude Desktop paths

Logs (macOS): ~/Library/Logs/Claude/mcp*.log

Full walkthrough: air.thalus.ai/docs/mcp-air-setup

Capabilities

Tools (25)

Composite wait tools use the MCP Tasks extension and return a task handle immediately instead of blocking for up to 30 minutes. Clients without Tasks support should poll with air_get_assessment or air_list_documents manually.

Resources (3 templates)

Prompts (3)

Typical workflow

1. air_list_domains → obtain domainPid

2. air_list_projects → obtain projectPid (or air_create_project with fullPipeline)

3. Upload evidence: air_run_assessment_from_file or manual init → PUT → complete → air_wait_for_document_extraction

4. air_start_assessment with artifactPids from air_list_artifacts

5. air_wait_for_assessment

6. air_get_assessment_report or read the air://assessments/{id}/report resource

See the Integration flow guide for the underlying HTTP API sequence.

Development

Contributors: see AGENTS.md for build, test, publish, and optional AIR_API_URL override.

git clone https://github.com/VericyIO/mcp-air.git
cd mcp-air && pnpm install && pnpm build
pnpm test

Documentation

Security

• The MCP process runs with your OS user privileges. Tools such as air_run_assessment_from_file can read any local path your user can access.

• Pin the package version in production (@thalus-ai/mcp-air@1.1.0) rather than floating @latest.

• Use least-privilege API key scopes. Write tools (air_start_assessment, uploads) consume organization credits.

• Never commit API keys. Use env or envFile in MCP client configuration.

License

MIT — see LICENSE.

Related repositories

• VericyIO/mcp-air — this server (source)

• VericyIO/thalus-air-skills — optional agent skills for MCP workflows

Maintainer notes (build, publish, constants sync): see AGENTS.md.