MCP Server

The @air/mcp package connects MCP-compatible AI clients to an Air workspace. It exposes tools for finding and previewing assets, organizing boards, applying tags and custom fields, importing files from URLs, and uploading local files.

The server supports:

• STDIO for clients that launch the package as a local child process. This is the recommended setup for desktop and coding clients.
• Streamable HTTP for local HTTP-capable clients and development.

Prerequisites

• Node.js 18 or newer
• An Air API key and workspace ID. See Getting Started for credential setup.

Configuration

The server reads these environment variables:

Credentials stay in the MCP server process. Do not place them in prompts or tool arguments.

Command-line options

HTTP mode binds to 127.0.0.1 and serves MCP requests at /mcp.

Set up a client

Claude Desktop

Add the server to your Claude Desktop config. On macOS, the file is ~/Library/Application Support/Claude/claude_desktop_config.json.

JSON

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

If Claude Desktop does not load the Node.js version from your shell profile, set command to the full path of a Node 18+ npx executable. See the Claude Desktop MCP guide.

Claude Code

Bash

claude mcp add \
  --env AIR_API_KEY=your-api-key \
  --env AIR_WORKSPACE_ID=your-workspace-id \
  --transport stdio \
  air \
  -- npx -y @air/mcp

See the Claude Code MCP documentation.

Codex

Add the server to ~/.codex/config.toml:

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 use the CLI:

Bash

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

See the Codex MCP documentation.

Cursor

Add the server to .cursor/mcp.json in a project or ~/.cursor/mcp.json globally:

JSON

See the Cursor MCP documentation.

Windsurf

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

JSON

See the Windsurf MCP documentation.

VS Code with GitHub Copilot

Add the server to .vscode/mcp.json, or open the user-level file with MCP: Open User Configuration:

JSON

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

Use Copilot in Agent mode to call MCP tools. See the VS Code MCP documentation.

Zed

Add the server to ~/.config/zed/settings.json:

JSON

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

See the Zed context server documentation.

Run with Streamable HTTP

Start a local HTTP server with credentials in the process environment:

Bash

AIR_API_KEY=your-api-key \
AIR_WORKSPACE_ID=your-workspace-id \
npx -y @air/mcp --http

Connect a local HTTP-capable MCP client to:

Text

http://localhost:3000/mcp

For example, add --port 4000 to choose another initial port or --debug to inspect MCP traffic.

Tool reference

The server registers 23 tools in six categories. A parameter followed by ? is optional.

List tools return a JSON object with data, pagination, and total. To request another page, pass the returned pagination cursor into the next call.

Assets

Boards

Tags

Custom fields

Imports

Uploads

filePath must be an absolute path that the MCP server process can read. For STDIO, this is normally the same machine as the client. For HTTP, the path refers to the server machine, not the machine running the remote client.

Tool behavior

Canonical Air URLs

get_asset, get_board, create_board, create_import, and upload_asset return a canonical url when applicable. Agents should use this field instead of constructing Air URLs from asset, version, or board IDs.

Asset images and thumbnails

get_asset_image returns an MCP image content block that supported clients can render directly. list_assets and list_nested_assets can include image content blocks by setting includeThumbnails: true.

For list calls, thumbnail fetching is limited to the first 10 returned assets. Images are fetched only from trusted Air or Imgix HTTPS hosts.

Custom-field values

update_asset_custom_field fetches the custom-field definition and validates values before updating the asset:

• For plain-text and date fields, pass value. Pass null to clear it.
• For single-select and multi-select fields, pass values as an array of { "id": "option-uuid" } objects. Pass null to clear the selection.
• A select field also accepts one option ID through value; the server validates the ID and converts it to values.
• Do not pass both value and values.
• Select option IDs are validated against the field's available options.

The customFields parameter accepted by create_import and upload_asset uses an array of objects with this shape:

JSON

[\
  {\
    "id": "text-or-date-field-id",\
    "value": "text-or-date-value"\\
  },\
  {\
    "id": "select-field-id",\
    "values": [{ "id": "select-option-id" }]\
  }\
]

Use the member appropriate for the field type. The tags parameter for imports and uploads is an array of { "id": "tag-id" } objects.

Imports and uploads

URL imports are asynchronous. After create_import, call get_import_status with the returned import task ID until the status is succeeded or failed.

Pass assetId to create_import or upload_asset to add the new file as a version of an existing asset. Pass parentBoardId to place a newly created asset in a board.

For create_import, fileName excludes the extension, ext excludes the leading dot, and recordedAt is an ISO 8601 date string.

Errors

Air API failures are returned as MCP tool errors containing the HTTP status and API error message. Invalid custom-field input is returned as a tool error with guidance about the expected value shape or valid select options.