MCP Server

The @air/mcp package is an MCP server that connects any MCP-compatible AI client to your Air workspace. It enables asset search, board management, tagging, custom fields, and more — directly from tools like Claude, Cursor, Windsurf, and ChatGPT.

Supports both STDIO (direct process) and HTTP/SSE (localhost server) transports.

Prerequisites

• Node.js 18+
• An Air API key and workspace ID — see Getting Started for details on obtaining credentials

Setup

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

nvm users: Claude Desktop doesn't load your shell profile, so it may use the wrong Node version. If you get engine errors, use the full path to a Node 20+ npx instead:

JSON

"command": "/Users/you/.nvm/versions/node/v20.19.4/bin/npx"

Find your path with nvm which 20 in a terminal.

See Claude Desktop MCP docs for more details.

Claude Code

claude mcp add air -t stdio -e AIR_API_KEY=your-api-key -e AIR_WORKSPACE_ID=your-workspace-id -- npx -y @air/mcp

See Claude Code MCP docs for more details.

Codex

Add to your Codex config (~/.codex/config.toml):

[mcp_servers.air]
command = "npx"
args = ["-y", "@air/mcp"]

[mcp_servers.air.env]
AIR_API_KEY = "your-api-key"
AIR_WORKSPACE_ID = "your-workspace-id"

Or add via the CLI:

codex mcp add air --env AIR_API_KEY=your-api-key --env AIR_WORKSPACE_ID=your-workspace-id -- npx -y @air/mcp

See Codex MCP docs for more details on configuring MCP servers in Codex.

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

See Cursor MCP docs for more details.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

See Windsurf MCP docs for more details.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project, or open the user-level config via the MCP: Open User Configuration command:

{
  "servers": {
    "air": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

Make sure to use Copilot in Agent mode to access MCP tools. See VS Code MCP docs for more details.

Zed

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "air": {
      "command": "npx",
      "args": ["-y", "@air/mcp"],
      "env": {
        "AIR_API_KEY": "your-api-key",
        "AIR_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

See Zed MCP docs for more details.

ChatGPT Desktop (HTTP/SSE)

ChatGPT desktop does not support STDIO MCP servers — it only supports MCP via HTTP. To connect it to a locally running Air MCP server:

1. Install the package:

npm install @air/mcp

2. Create a .env file in your project:

AIR_API_KEY=your-api-key
AIR_WORKSPACE_ID=your-workspace-id

3. Start the HTTP server:

npx -y @air/mcp -- --http

4. In ChatGPT, open Settings > Connectors > Add connector.
5. Set the URL to:

http://localhost:3000/mcp

6. Set authentication to None and save.

Note: ChatGPT MCP support requires Developer mode and is currently available on Windows and web. macOS support may be limited — see ChatGPT MCP docs for the latest.

Available tools

Assets

Boards

Tags

Custom Fields