MCP Server

The Airweave MCP server implements the Model Context Protocol to let AI assistants search your synced data. It supports two deployment modes: local (stdio) for desktop AI clients and hosted (Streamable HTTP) for cloud platforms, with two authentication methods: API key and OAuth 2.0.

Prerequisites

Before you start you’ll need:

• A collection with data: at least one source connection must have completed its initial sync. See the Quickstart if you need to set this up.
• An API key (for API key auth): Create one in the Airweave dashboard under API Keys.
• No setup needed (for OAuth auth): The hosted MCP server handles OAuth 2.0 via Auth0 automatically — users authenticate through a browser redirect.

Local mode (Desktop AI clients)

Local mode runs the MCP server as a local process that communicates over stdio. This is the standard setup for desktop AI assistants.

1
{
2
  "mcpServers": {
3
    "airweave-search": {
4
      "command": "npx",
5
      "args": ["-y", "airweave-mcp-search"],
6
      "env": {
7
        "AIRWEAVE_API_KEY": "your-api-key",
8
        "AIRWEAVE_COLLECTION": "your-collection-id"
9
      }
10
    }
11
  }
12
}

Environment variables (local mode)

Hosted mode (Cloud AI platforms)

Hosted mode runs the MCP server as a stateless HTTP service at https://mcp.airweave.ai/mcp. This is the setup for cloud-based AI platforms that need a remote MCP endpoint. The server uses the Streamable HTTP transport (MCP 2025-03-26).

Each request is fully independent: authentication and collection selection happen per-request via HTTP headers. No sessions or server-side state.

The hosted server supports two authentication methods: API key (simple, direct) and OAuth 2.0 (browser-based login). Both can be used at the same time.

1
{
2
  "mcpServers": {
3
    "airweave-search": {
4
      "command": "npx",
5
      "args": [
6
        "-y", "mcp-remote",
7
        "https://mcp.airweave.ai/mcp",
8
        "--header", "X-Collection-Readable-ID: your-collection-id"
9
      ]
10
    }
11
  }
12
}

Authentication (hosted mode)

The server supports two authentication methods. When both are present, X-API-Key takes priority.

API key authentication:

OAuth 2.0 authentication:

The hosted server supports OAuth 2.0 with PKCE via Auth0. MCP clients that support RFC 7591 Dynamic Client Registration (like mcp-remote) handle this automatically:

1. The client discovers OAuth metadata at /.well-known/oauth-authorization-server
2. The client registers itself at /register (dynamic client registration)
3. The user is redirected to Auth0 for login via /authorize
4. After login, Auth0 redirects back to /oauth/callback
5. The client exchanges the authorization code for tokens at /token
6. Subsequent requests use Authorization: Bearer <access-token>

When a Bearer token is present and OAuth is enabled, the server verifies it as a JWT. If verification fails, it falls back to treating the token as an API key.

Collection selection (hosted mode)

Endpoints

Available tools

The MCP server exposes two tools to AI assistants:

search-{collection}

The primary search tool. The tool name includes the collection ID so the AI assistant knows which dataset it’s searching (e.g., search-my-docs).

The tool supports all three search tiers, selectable via the tier parameter:

Tiers at a glance:

• instant — Direct vector search. Fastest (sub-second). Use for straightforward lookups.
• classic — An LLM plans the search strategy, then executes it. Good balance of speed (~2–5 s) and quality. This is the default.
• agentic — A multi-step agent iteratively searches, reads, and navigates your data. Deepest results, highest latency.

Filters:

Filters let you narrow results by metadata. Each filter group is a list of conditions combined with AND; multiple groups are combined with OR.

1
{
2
  "filter": [
3
    {
4
      "conditions": [
5
        {
6
          "field": "airweave_system_metadata.source_name",
7
          "operator": "equals",
8
          "value": "notion"
9
        }
10
      ]
11
    }
12
  ]
13
}

See the Search documentation for the full list of filterable fields and operators.

get-config

Returns the current server configuration: collection ID, base URL, API key status, and available tools. No parameters.

Architecture

AI Assistant (Cursor, Claude, OpenAI, VS Code)
         │
         ├── stdio (local mode)
         │        └── npx airweave-mcp-search
         │
         └── HTTP POST (hosted mode)
                  └── https://mcp.airweave.ai/mcp
                           │
                     MCP Server (Node.js)
                       │         │
                  API key auth   OAuth 2.0
                       │         │ (Auth0 + Redis)
                       └────┬────┘
                            │
                      Airweave API
                            │
                      POST /collections/{id}/search/{tier}
                      (instant | classic | agentic)

• Local mode: One MCP server process per user. API key and collection are set via environment variables. Communication over stdio.
• Hosted mode: Stateless HTTP server. A fresh MCP server instance is created for each request. Supports API key auth (via headers) and OAuth 2.0 (via Auth0).

In both modes, the MCP server validates parameters, calls the appropriate search tier endpoint, and formats results for the AI assistant.

Self-hosting

If you’re running Airweave on your own infrastructure, point the MCP server at your instance:

Local mode:

1
{
2
  "mcpServers": {
3
    "airweave-search": {
4
      "command": "npx",
5
      "args": ["-y", "airweave-mcp-search"],
6
      "env": {
7
        "AIRWEAVE_API_KEY": "your-api-key",
8
        "AIRWEAVE_COLLECTION": "your-collection-id",
9
        "AIRWEAVE_BASE_URL": "https://your-airweave-instance.com"
10
      }
11
    }
12
  }
13
}

Hosted mode (Docker):

$
docker run -p 8080:8080 \
>
  -e AIRWEAVE_COLLECTION=your-default-collection \
>
  -e AIRWEAVE_BASE_URL=https://your-airweave-instance.com \
>
  your-registry/mcp:latest

The hosted mode Docker image exposes port 8080 with a health check at /health. Self-hosted instances use API key authentication. OAuth is only available on the managed Airweave platform (mcp.airweave.ai).