MCP Server - Airweave

The Airweave MCP server provides comprehensive search capabilities for AI assistants like Claude Desktop, Cursor, and OpenAI Agent Builder through the Model Context Protocol.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources and tools. The Airweave MCP server makes your synced data searchable directly from AI assistants.

Features

Semantic Search: Natural language queries across all your connected data sources
Advanced Parameters: Full control over search method, ranking, reranking, and more
AI Completion: Get AI-generated answers from search results
Multi-tenant: Hosted mode supports thousands of users with per-session isolation
Production-Ready: Redis-backed sessions, rate limiting, OAuth2 support
Two Deployment Modes: Local (stdio) for desktop clients, Hosted (HTTP) for cloud platforms

Installation

Quick Start (Recommended)

The easiest way to use the MCP server locally:

npx airweave-mcp-search

Global Installation

npm install -g airweave-mcp-search
airweave-mcp-search

From Source

git clone https://github.com/airweave-ai/airweave.git
cd airweave/mcp
npm install
npm run build
npm run start

Configuration

Local Mode (Desktop AI Clients)

For Claude Desktop, Cursor, and other desktop AI assistants.

Required Environment Variables

AIRWEAVE_API_KEY: Your Airweave API key (get from dashboard)
AIRWEAVE_COLLECTION: The readable ID of the collection to search

Optional Environment Variables

AIRWEAVE_BASE_URL: Base URL for the Airweave API (default: https://api.airweave.ai)

Hosted Mode (Cloud AI Platforms)

For OpenAI Agent Builder and cloud-based AI platforms.

Production Endpoint

https://mcp.airweave.ai/mcp

Required Headers

X-API-Key: Your Airweave API key
X-Collection-Readable-ID: The readable ID of the collection to search

Alternative: OAuth2 Authentication

Authorization: Bearer <oauth-access-token>

Hosted mode enables true multi-tenancy: each user can search their own collections without requiring separate server deployments.

Setup Guides

Claude Desktop

Add the following to your Claude Desktop configuration file: Location: ~/.config/Claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%/Claude/claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "airweave-search": {
      "command": "npx",
      "args": ["airweave-mcp-search"],
      "env": {
        "AIRWEAVE_API_KEY": "your-api-key-here",
        "AIRWEAVE_COLLECTION": "your-collection-id",
        "AIRWEAVE_BASE_URL": "https://api.airweave.ai"
      }
    }
  }
}

For self-hosted Airweave:

{
  "mcpServers": {
    "airweave-search": {
      "command": "node",
      "args": ["/absolute/path/to/airweave/mcp/build/index.js"],
      "env": {
        "AIRWEAVE_API_KEY": "your-api-key-here",
        "AIRWEAVE_COLLECTION": "your-collection-id",
        "AIRWEAVE_BASE_URL": "http://localhost:8001"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "airweave-search": {
      "command": "npx",
      "args": ["airweave-mcp-search"],
      "env": {
        "AIRWEAVE_API_KEY": "your-api-key-here",
        "AIRWEAVE_COLLECTION": "your-collection-id",
        "AIRWEAVE_BASE_URL": "https://api.airweave.ai"
      }
    }
  }
}

OpenAI Agent Builder

Configure MCP Server

In OpenAI Agent Builder, add a new MCP server:MCP Server URL: https://mcp.airweave.ai/mcp

Add Authentication Headers

Add custom headers:Header 1:

Name: X-API-Key
Value: <your-airweave-api-key>

Header 2:

Name: X-Collection-Readable-ID
Value: <your-collection-readable-id>

(Optional) Use OAuth2

For production deployments, use OAuth2 instead:Header 1:

Name: Authorization
Value: Bearer <oauth-access-token>

Collection access is determined automatically from your account.

Available Tools

Once configured, the MCP server exposes two tools to AI assistants:

`search-{collection}`

Searches within the configured Airweave collection with full parameter control. Parameters:

query

string

required

The search query text to find relevant documents and data

response_type

string

default:"raw"

Format of the response:

raw: Returns search results with scores and metadata
completion: Returns AI-generated natural language answers

limit

integer

default:"100"

Maximum number of results to return (1-1000)

offset

integer

default:"0"

Number of results to skip for pagination (≥0)

recency_bias

float

How much to weigh recency vs similarity (0.0 to 1.0)

0: No recency effect
1: Rank by recency only

score_threshold

float

Minimum similarity score threshold (0.0 to 1.0). Only return results above this score.

search_method

string

default:"hybrid"

Search method:

hybrid: Combines neural (semantic) + keyword search (default)
neural: Semantic search only
keyword: Text matching only

expansion_strategy

string

default:"auto"

Query expansion strategy:

auto: Generates query variations (default)
llm: AI-powered expansion
no_expansion: Use exact query

enable_reranking

boolean

default:"true"

Enable LLM-based reranking to improve result relevance

enable_query_interpretation

boolean

default:"true"

Enable automatic filter extraction from natural language queries

`get-config`

Shows the current server configuration and status. Parameters: None

Usage Examples

Once configured, you can use natural language to search:

Basic Search
AI-Generated Answer
Recent Results
Pagination
High-Quality Results

Search for customer feedback about pricing

The assistant will call the search-{collection} tool with:

{
  "query": "customer feedback about pricing"
}

Search for billing issues and give me a summary

The assistant will call the tool with:

{
  "query": "billing issues",
  "response_type": "completion"
}

Find the most recent documents about API changes

The assistant will call the tool with:

{
  "query": "API changes",
  "recency_bias": 0.8
}

Show me results 11-20 for support tickets

The assistant will call the tool with:

{
  "query": "support tickets",
  "limit": 10,
  "offset": 10
}

Find highly relevant documents about machine learning

The assistant will call the tool with:

{
  "query": "machine learning",
  "score_threshold": 0.8,
  "enable_reranking": true
}

Architecture

Local Mode (Stdio Transport)

Claude Desktop/Cursor → Stdio Transport → MCP Server → Airweave API
                     ↑
                Environment Variables (API Key, Collection)

Uses standard input/output (stdio)
Runs as a subprocess on the user’s machine
Configuration via environment variables

Hosted Mode (HTTP Transport)

Cloud AI Platform → HTTPS → Load Balancer → MCP HTTP Server (Pods)
                                                     ↓
                                             Redis Session Store
                                                     ↓
                                              Airweave API

Key Components:

Session Manager: Redis-backed distributed sessions with local caching
OAuth Validator: Token validation with 1-hour caching
Rate Limiter: Per-API-key rate limiting (100 sessions/hour)
Multi-tenant: Per-session isolation with separate McpServer instances

Hosted Mode Features

Session Management

30-minute session TTL: Automatic expiration after inactivity
Distributed Sessions: Redis stores session metadata
Stateless Design: Any pod can handle any request
Session Binding: IP + User-Agent validation prevents hijacking

Rate Limiting

100 sessions per hour per API key
Automatic cleanup of expired sessions
Rate limit resets every hour

Security

API keys are hashed (SHA-256) before storage
Keys never logged or exposed in error messages
Session binding prevents session hijacking
OAuth2 token validation and caching

Testing

Test Hosted Mode

You can test the hosted MCP server using curl:

# 1. Check server health
curl https://mcp.airweave.ai/health

# 2. List available tools
curl -X POST https://mcp.airweave.ai/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Collection-Readable-ID: your-collection-id" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

# 3. Execute a search
curl -X POST https://mcp.airweave.ai/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Collection-Readable-ID: your-collection-id" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search-your-collection-id",
      "arguments": {
        "query": "test query",
        "limit": 5
      }
    },
    "id": 2
  }'

Run Tests Locally

cd mcp

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Test specific components
npm run test:mcp     # MCP server tests
npm run test:http    # HTTP transport tests

Troubleshooting

Local Mode Issues

“Error: AIRWEAVE_API_KEY environment variable is required”

Set the AIRWEAVE_API_KEY environment variable
Verify your API key is valid in the Airweave dashboard

“Error: AIRWEAVE_COLLECTION environment variable is required”

Set the AIRWEAVE_COLLECTION to your collection’s readable ID
Verify the collection exists in your Airweave instance

“Airweave API error (404)”

Check that the collection ID is correct
Verify the collection exists and you have access

“Airweave API error (401)”

Check that your API key is valid
Ensure the API key has necessary permissions

Hosted Mode Issues

“Rate limit exceeded”

You’ve created more than 100 sessions in the past hour
Wait for the rate limit window to reset

“Session not found”

Session expired after 30 minutes of inactivity
Create a new session (omit mcp-session-id header)

“Invalid OAuth token”

Token may be expired or revoked
Obtain a new OAuth access token

Debug Mode

The MCP server logs diagnostic information to stderr:

# Local mode - check stderr output
# Look for messages like:
# "Airweave MCP Search Server started"
# "Collection: your-collection-id"
# "Base URL: https://api.airweave.ai"

Package Information

Package Name: airweave-mcp-search
Version: 0.5.7
MCP Protocol: 2025-03-26 (Streamable HTTP) + legacy stdio
Node.js: 20.0.0 or higher
License: MIT

Source Code

The MCP server source code is available in the Airweave monorepo:

GitHub: github.com/airweave-ai/airweave/tree/main/mcp
npm: npmjs.com/package/airweave-mcp-search

Need Help?

MCP Documentation - Learn about Model Context Protocol
Airweave Discord - Get help from the community
GitHub Issues - Report bugs or request features
Security Issues - Report security vulnerabilities

Getting Started

Core Features

Data Sources

Integrations

Self-Hosting

Advanced

Contributing

​What is MCP?

​Features

​Installation

​Quick Start (Recommended)

​Global Installation

​From Source

​Configuration

​Local Mode (Desktop AI Clients)

​Required Environment Variables

​Optional Environment Variables

​Hosted Mode (Cloud AI Platforms)

​Production Endpoint

​Required Headers

​Alternative: OAuth2 Authentication

​Setup Guides

​Claude Desktop

​Cursor

​OpenAI Agent Builder

​Available Tools

​search-{collection}

​get-config

​Usage Examples

​Architecture

​Local Mode (Stdio Transport)

​Hosted Mode (HTTP Transport)

​Hosted Mode Features

​Session Management

​Rate Limiting

​Security

​Testing

​Test Hosted Mode

​Run Tests Locally

​Troubleshooting

​Local Mode Issues

​Hosted Mode Issues

​Debug Mode

​Package Information

​Source Code

​Need Help?

What is MCP?

Features

Installation

Quick Start (Recommended)

Global Installation

From Source

Configuration

Local Mode (Desktop AI Clients)

Required Environment Variables

Optional Environment Variables

Hosted Mode (Cloud AI Platforms)

Production Endpoint

Required Headers

Alternative: OAuth2 Authentication

Setup Guides

Claude Desktop

Cursor

OpenAI Agent Builder

Available Tools

`search-{collection}`

`get-config`

Usage Examples

Architecture

Local Mode (Stdio Transport)

Hosted Mode (HTTP Transport)

Hosted Mode Features

Session Management

Rate Limiting

Security

Testing

Test Hosted Mode

Run Tests Locally

Troubleshooting

Local Mode Issues

Hosted Mode Issues

Debug Mode

Package Information

Source Code

Need Help?