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.2.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.2.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.2.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/.

Remote clients authorize with OAuth 2.0 against https://api.air.thalus.ai (authorization code + PKCE S256, dynamic client registration). Discovery starts from the 401 on /mcp, whose WWW-Authenticate header points at https://api.air.thalus.ai/.well-known/oauth-protected-resource. Access tokens must carry https://mcp.air.thalus.ai/mcp as their audience.

End-user setup: Remote MCP server (OAuth).

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 (28 stdio / 26 remote)

† stdio only

air_wait_for_* block with exponential backoff until the resource is ready or timeoutMs elapses, then return ready: false with the last observed status — call again with the same pid to keep waiting. Pipeline tools (air_run_assessment_from_file, air_run_full_assessment_pipeline) use the MCP Tasks extension and return a task handle immediately, so they require a Tasks-capable client.

Surface differences: stdio vs remote

Uploads work the same on both surfaces, through the presigned pair. The client must be able to reach the storage host to perform the PUT.

Remote waits are capped at 240s per call (hosted clients abort a tool call at 300s); stdio keeps the longer 10 / 30 minute ceilings.

Uploading to the presigned URL

The presigned URL signs content-type and host only. Send the file bytes with the same contentType you passed to air_upload_document_init and nothing else:

curl -X PUT --upload-file ./model-card.pdf \
  -H 'Content-Type: application/pdf' \
  "$UPLOAD_URL"

Do not add x-amz-* headers. AWS SDKs and aws s3 cp attach x-amz-checksum-crc32 and x-amz-sdk-checksum-algorithm by default; those are not part of the signature and the PUT fails with SignatureDoesNotMatch. With boto3, set AWS_REQUEST_CHECKSUM_CALCULATION=when_required, or use a plain HTTP client.

Reading a large report

A full report can run past what a single tool result can carry, so air_get_assessment_report degrades in steps rather than getting truncated:

The section index lists every section with its serialized size and item count, so a caller that overflows can pick deliberately instead of guessing. List sections page automatically: ask for riskRegister and you get as many entries as fit plus a nextOffset to resume from.

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 (stdio), or air_upload_document_init → PUT → air_upload_document_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.2.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.

Privacy

The AIR cloud (Thalus) processes the documents, project data, and account information you submit through this server in order to run assessments and generate reports. See the Privacy Policy for details on data collection, usage and storage, third-party sharing, and retention. Contact privacy@thalus.ai with privacy questions.

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.