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).

Parameters:

Natural language examples: the AI assistant will map these to the correct parameters automatically:

• “Find the first 5 results” → limit: 5
• “Show me results 11-20” → limit: 10, offset: 10
• “Give me a summary” → response_type: "completion"
• “Find the most recent documents” → recency_bias: 0.8
• “Find high-quality results only” → score_threshold: 0.8
• “Use keyword search” → search_method: "keyword"
• “Don’t expand my query” → expansion_strategy: "no_expansion"
• “Disable reranking” → enable_reranking: false

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

• 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 is a thin wrapper around the Airweave SDK. It validates parameters, calls the search API, 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).