> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.airweave.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server. # MCP Server The Airweave MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io/) 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](/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. #### Cursor > **Requirement**: Cursor version 0.45.6 or later 1. Open **Cursor Settings** 2. Go to **Features > MCP Servers** 3. Click **"+ Add new global MCP server"** 4. Add this configuration: ```json title="Cursor Configuration" { "mcpServers": { "airweave-search": { "command": "npx", "args": ["-y", "airweave-mcp-search"], "env": { "AIRWEAVE_API_KEY": "your-api-key", "AIRWEAVE_COLLECTION": "your-collection-id" } } } } ``` #### Claude Desktop Add the following to your Claude Desktop config file and restart Claude Desktop afterwards. After a restart the search tool will appear in Claude's composer. * **macOS/Linux**: `~/.claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\claude\claude_desktop_config.json` ```json title="Claude Desktop Configuration" { "mcpServers": { "airweave-search": { "command": "npx", "args": ["-y", "airweave-mcp-search"], "env": { "AIRWEAVE_API_KEY": "your-api-key", "AIRWEAVE_COLLECTION": "your-collection-id" } } } } ``` #### VS Code Add to your User Settings (JSON) via **Ctrl+Shift+P** → **"Preferences: Open User Settings (JSON)"**: ```json title="VS Code Configuration" { "mcp": { "inputs": [ { "type": "promptString", "id": "airweaveApiKey", "description": "Airweave API Key", "password": true }, { "type": "promptString", "id": "airweaveCollection", "description": "Airweave Collection ID" } ], "servers": { "airweave": { "command": "npx", "args": ["-y", "airweave-mcp-search"], "env": { "AIRWEAVE_API_KEY": "${input:airweaveApiKey}", "AIRWEAVE_COLLECTION": "${input:airweaveCollection}" } } } } } ``` ### Environment variables (local mode) | Variable | Required | Description | | --------------------- | -------- | ----------------------------------------------------------------------- | | `AIRWEAVE_API_KEY` | Yes | Authenticates the MCP server with the Airweave API | | `AIRWEAVE_COLLECTION` | Yes | Readable ID of the collection to query | | `AIRWEAVE_BASE_URL` | No | Override for self-hosted instances (default: `https://api.airweave.ai`) | --- ## 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. #### Cursor (OAuth) Use `mcp-remote` to handle the OAuth flow automatically. On first connection, a browser window opens for login: ```json title="~/.cursor/mcp.json" { "mcpServers": { "airweave-search": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.airweave.ai/mcp", "--header", "X-Collection-Readable-ID: your-collection-id" ] } } } ``` `mcp-remote` discovers the OAuth metadata at `/.well-known/oauth-authorization-server`, registers a client, and manages token refresh transparently. #### Cursor (API key) Use Cursor's native Streamable HTTP support with your API key — no extra tooling needed: ```json title="~/.cursor/mcp.json" { "mcpServers": { "airweave-search": { "url": "https://mcp.airweave.ai/mcp", "headers": { "X-API-Key": "your-api-key", "X-Collection-Readable-ID": "your-collection-id" } } } } ``` #### OpenAI Agent Builder In the OpenAI Agent Builder, add a new MCP tool with: * **URL**: `https://mcp.airweave.ai/mcp` * **Headers**: * `X-API-Key`: Your Airweave API key * `X-Collection-Readable-ID`: Your collection's readable ID #### Any HTTP MCP Client Send a POST request to the MCP endpoint. The server speaks standard MCP over Streamable HTTP: ```bash title="Initialize" curl -X POST https://mcp.airweave.ai/mcp \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -H "X-API-Key: your-api-key" \ -H "X-Collection-Readable-ID: your-collection-id" \ -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "my-client", "version": "1.0.0"}}, "id": 1}' ``` ### Authentication (hosted mode) The server supports two authentication methods. When both are present, `X-API-Key` takes priority. **API key authentication:** | Method | Example | | -------------------------------- | ------------------------------------ | | `X-API-Key` header (recommended) | `X-API-Key: your-api-key` | | `Authorization: Bearer` header | `Authorization: Bearer your-api-key` | **OAuth 2.0 authentication:** The hosted server supports [OAuth 2.0 with PKCE](https://oauth.net/2/pkce/) via Auth0. MCP clients that support [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) (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 ` 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) | Header | Required | Description | | -------------------------- | -------- | ------------------------------------------------------------------- | | `X-Collection-Readable-ID` | No | Collection to search. Falls back to server default if not provided. | ### Endpoints | Method | Path | Description | | -------- | --------- | -------------------------------------------- | | `POST` | `/mcp` | Main MCP endpoint (Streamable HTTP) | | `DELETE` | `/mcp` | Session termination (no-op, returns success) | | `GET` | `/health` | Health check | | `GET` | `/` | Server info and authentication docs | --- ## 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](/search#search-tiers), selectable via the `tier` parameter: | Parameter | Type | Required | Default | Description | | -------------------- | ----------------------------------------- | -------- | ----------- | --------------------------------------------------------------- | | `query` | string | Yes | — | The search query text | | `tier` | `"instant"` \| `"classic"` \| `"agentic"` | No | `"classic"` | Search tier — controls depth vs. speed | | `limit` | number | No | 100 | Maximum results to return (1–1000) | | `offset` | number | No | 0 | Results to skip for pagination (instant and classic only) | | `retrieval_strategy` | `"hybrid"` \| `"semantic"` \| `"keyword"` | No | `"hybrid"` | Retrieval strategy (instant tier only) | | `thinking` | boolean | No | `false` | Enable extended thinking / chain-of-thought (agentic tier only) | | `filter` | FilterGroup\[] | No | — | Structured filters for precise matching | **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. ```json title="Example: only Notion results" { "filter": [ { "conditions": [ { "field": "airweave_system_metadata.source_name", "operator": "equals", "value": "notion" } ] } ] } ``` See the [Search documentation](/search#filters) 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](/search#search-tiers), 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:** ```json { "mcpServers": { "airweave-search": { "command": "npx", "args": ["-y", "airweave-mcp-search"], "env": { "AIRWEAVE_API_KEY": "your-api-key", "AIRWEAVE_COLLECTION": "your-collection-id", "AIRWEAVE_BASE_URL": "https://your-airweave-instance.com" } } } } ``` **Hosted mode (Docker):** ```bash 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`).