AIR MCP server setup

Use @thalus-ai/mcp-air to run AIR assessments and read project data from any MCP-compatible client — Cursor, Claude Code, Claude Desktop, VS Code (with GitHub Copilot), Windsurf, and others.

The MCP server runs on your machine (stdio) or as a hosted Streamable HTTP endpoint for Claude Directory. Assessments and report generation run on Thalus cloud infrastructure.

Mode	Endpoint	Auth
Local stdio	npx @thalus-ai/mcp-air	Domain API key, a stored credential, or none (setup mode)
Remote HTTP	https://mcp.air.thalus.ai/mcp	OAuth (portal consent) or Bearer API key

For OAuth scopes, consent, and Directory connect details, see Remote MCP OAuth.

What you need

1. An AIR organization with active billing (assessments consume credits) — or none at all: see Start without an account.
2. For local stdio: a domain-scoped API key, or nothing. With no credential the server starts in setup mode so you can create an account from the conversation. See Credentials on stdio.
3. For remote / Directory: an AIR login with domain owner/admin role (consent creates a service-account API key for you).

For API key presets and HTTP integration details, see Getting started and Authentication.

Install the MCP server

Every supported client runs the same local process (npx @thalus-ai/mcp-air). Only the config file location and root JSON key differ.

Server configuration

Cursor, Claude Code, Claude Desktop, Windsurf — root key mcpServers:

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

VS Code — root key servers in .vscode/mcp.json or your user MCP config (VS Code MCP docs):

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

Set AIR_API_KEY in your shell before launching the client, or use envFile where your client supports it. Pin the version in args as shown.

Choose your client

Client	Where to add the config	After saving
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects)	Restart Cursor
Claude Code	.mcp.json (project) or ~/.claude.json (user) — see Claude Code MCP docs	Reload MCP (/mcp) or start a new session
Claude Desktop	Platform paths below	Quit and reopen Claude Desktop
VS Code	.vscode/mcp.json (workspace) or MCP: Open User Configuration (global)	Reload window; use Agent mode for MCP tools
Windsurf	~/.codeium/windsurf/mcp_config.json	Restart Windsurf
Other	Your client's MCP documentation	Same command, args, and AIR_API_KEY as above

Cursor

Copy the mcpServers block into .cursor/mcp.json. See the mcp-air README for a copyable example.

Claude Code

Option A — CLI (user scope; replace the placeholder with your key):

claude mcp add --env AIR_API_KEY=your-domain-key --transport stdio air -- npx -y @thalus-ai/mcp-air@1.3.0

Option B — JSON — add the mcpServers block to .mcp.json in your project root (share with your team) or to ~/.claude.json for all projects.

Claude Desktop

Add the mcpServers block to your platform config file:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

VS Code

Add the servers block to .vscode/mcp.json, or run MCP: Add Server and enter npx with args -y @thalus-ai/mcp-air@1.3.0. MCP tools are available in Copilot Agent mode.

Start without an account

The hosted server has not shipped this yet

Everything in this section is live on local stdio today. The remote connector at mcp.air.thalus.ai still asks for authorization before anything and gains this flow with its next deploy.

Both transports support this. On stdio, the server starts in setup mode when it finds no credential; on the remote connector, you can add AIR without a token. These need no credential: air_create_account, air_submit_feedback, air_sign_out (stdio), and the signup form's two callbacks.

On the remote transport, everything else is protected. The first time the assistant calls a protected tool without a token, the server answers HTTP 401 with a WWW-Authenticate challenge and your client shows its inline Connect card. You authorize in a popup, the client retries the same call, and the conversation continues — the turn is not lost. This is lazy authentication: the connector no longer refuses every request until you sign in first.

To create an account in chat:

1. Ask the assistant to create an AIR account. It calls air_create_account, which opens a form or a dialog depending on your client.
2. Type your name, work email and organization. You type them — the model supplies nothing, and what you type in the form does not enter its context.
3. Enter the code emailed to you, tick the terms box, then submit. The terms tick is read from the checkbox alone; the model cannot set it, and the API refuses the request without it.
4. On the remote transport, press the sign-in button: it gives your browser a session, so the OAuth consent screen appears directly next time. On stdio there is nothing more to do — the key is already stored and the full tool set is available.

New organizations start on the Free plan with one assessment credit per 30 days. Check it with air_get_credit_balance, and ask for more with air_request_credits — a form shows you the request before it is sent, and Thalus replies by email to the organization owner. Neither the credit request nor feedback asks the assistant for an email address; you can type a different one in the confirmation dialog if you want the reply elsewhere.

air_create_account uses the richest input your client offers:

Client capability	What happens
MCP Apps (Claude Code, Claude, VS Code)	A form renders in the conversation. Fields never reach the model at all.
Elicitation only	Two dialogs: details, then the code and the terms checkbox.
Neither	The portal signup link, and it stops — it will not ask the model for your details.

Credentials on stdio

The stdio server resolves a credential in this order, and starts either way:

Order	Source	Notes
1	AIR_API_KEY	Set in your MCP client config. Wins over anything on disk.
2	~/.air/credentials.json	Written by air_create_account. Override with AIR_CREDENTIALS_PATH.
3	none → setup mode	Only the tools that work without an account are offered.

The stored file holds a bearer key, so it is written with mode 0600 in a directory created 0700. The key is written to that file and never returned in a tool result, so it does not reach your conversation transcript or your client's logs. The file also records the API URL, org slug, domain pid, domain slug and creation time.

In setup mode only five tools are offered; the rest are registered but disabled. When an account is created the key is stored, the full surface is enabled, and the server emits tools/list_changed — no restart needed.

air_sign_out deletes the credential file and returns to setup mode; the account itself is untouched. If your key came from AIR_API_KEY there is no file to delete, and the tool says so instead of reporting a success: remove the variable from your client configuration and restart.

Signing out forgets the key on this machine — it does not revoke it. The key keeps working anywhere else it is held. If the machine was lost, shared, or is no longer yours, revoke the key itself in the portal: open your domain → API Keys, find the key for the MCP service account, and revoke it there.

Choose an API key preset

Preset	Use when
assessmentRunner	List domains and projects, start assessments, read reports on existing evidence
fullPipeline	Upload documents, search, domain portfolio, create projects, run file-based pipelines

If you want to…	You need
List domains/projects and run assessments on existing artifacts	assessmentRunner
Upload files or use air_run_assessment_from_file	fullPipeline
Use air_search or air_get_domain_portfolio	fullPipeline
Create projects with air_create_project	fullPipeline

Org-wide portfolio views, billing, and user administration are available in the AIR portal only — not through MCP.

Optional: agent skills

MCP exposes tools; Agent Skills teach your coding agent how to use them effectively (workflows, presets, long-running tasks).

npx skills add VericyIO/thalus-air-skills -g

Or install individual skills:

npx skills add VericyIO/thalus-air-skills --skill air-mcp-setup -g
npx skills add VericyIO/thalus-air-skills --skill air-mcp-assessments -g

Install skills after the MCP server is connected. See thalus-air-skills on GitHub.

Verify it works

1. Set AIR_API_KEY (use fullPipeline if you plan to test uploads).
2. In your client’s MCP settings, confirm the air server is connected.
3. Ask your agent: “Use air_list_domains and air_list_projects.”

You can also test with MCP Inspector:

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

What the server provides

Tools (35 stdio / 32 remote)

Category	Tools
Discovery	air_list_domains, air_get_domain, air_list_projects, air_get_project, air_create_project, air_search
Documents	air_list_documents, air_get_document_download_url, air_list_artifacts, air_get_artifact_text, air_upload_document_init, air_upload_document_complete
Assessments	air_list_assessments, air_get_assessment, air_get_assessment_report, air_get_assessment_summary, air_list_open_facts, air_submit_fact_answers, air_get_assessment_stages, air_get_assessment_input_artifacts, air_create_assessment_draft, air_start_assessment, air_retry_assessment
Portfolio	air_get_domain_portfolio
Pipelines	air_wait_for_document_extraction, air_wait_for_assessment, air_run_assessment_from_file†, air_run_full_assessment_pipeline†

| Account | air_create_account‡, air_signup_send_code‡§, air_signup_verify_code‡§, air_sign_out¶ | | Support | air_submit_feedback‡, air_request_credits, air_get_credit_balance |

† stdio only — both use the MCP Tasks extension, which hosted Claude clients do not support. ‡ Needs no credential. § Called by the signup form only; the model never sees them. ¶ stdio only.

The stdio count is one higher because air_sign_out manages the local credential file, and the hosted transport has none — there, OAuth is the credential.

No account or support tool needs an extra API key scope, so a key created before these tools existed still reaches them.

Resources

• air://assessments/{assessmentPid}/report
• air://assessments/{assessmentPid}/stages
• air://projects/{projectPid}/assessments
• ui://air/signup-form.html — the in-chat signup form (remote transport)

Prompts

• run-assessment-workflow
• review-assessment-report
• explore-portfolio

Typical workflow

1. air_list_domains → domainPid
2. air_list_projects → projectPid (or air_create_project with fullPipeline)
3. Add evidence — upload with fullPipeline (air_run_assessment_from_file or the upload tools), or reuse existing artifacts from air_list_artifacts
4. air_start_assessment with up to five artifactPids
5. Wait for completion (air_wait_for_assessment or poll with air_get_assessment)
6. air_get_assessment_report or read the report resource

Wait tools (air_wait_for_*) poll 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. Over stdio they wait up to 10 minutes (documents) or 30 minutes (assessments); over the hosted endpoint they cap at 4 minutes per call, because hosted clients abort a tool call at 5.

The pipeline tools (air_run_assessment_from_file, air_run_full_assessment_pipeline) return an MCP Tasks handle immediately and need a Tasks-capable client, so they are stdio only.

A full report can exceed what one tool result carries. air_get_assessment_report returns the whole report when it fits, otherwise a section index; pass section, plus offset and limit for list sections such as riskRegister. air_get_assessment_summary is the quickest triage.

See Integration flow for the underlying HTTP API.

Troubleshooting

Symptom	What to check
Server fails on start	AIR_API_KEY is set; check MCP logs (stderr)
401 on tool calls	Key is invalid or revoked — create a new key in the portal
403 on tool calls	Key preset is too narrow — use fullPipeline for uploads and search
402 on start assessment	Billing or credits — check the AIR portal
404 on portfolio or project	Wrong domain/project, or key scoped to a different domain

Security

• Never commit API keys. Use env or envFile in MCP config.
• Pin the package version in args (e.g. @thalus-ai/mcp-air@1.3.0).
• Use the narrowest API key preset that fits your workflow.
• Starting assessments and uploading documents consumes credits — review tool approvals in your client.
• air_run_assessment_from_file can read local files your OS user can access.

Learn more

Resource	Link
MCP server source	github.com/VericyIO/mcp-air
npm package	@thalus-ai/mcp-air
Agent skills	github.com/VericyIO/thalus-air-skills
API reference	air.thalus.ai/docs/api-reference
Integrator guides	Getting started