MCP Server Reference

The @lightfastai/mcp package provides a Model Context Protocol server that exposes Lightfast tools to AI assistants.

Installation

bash
npx @lightfastai/mcp
# or
npm install -g @lightfastai/mcp
npx @lightfastai/mcp
# or
npm install -g @lightfastai/mcp

CLI Options

bash
npx @lightfastai/mcp [options]
npx @lightfastai/mcp [options]

Environment Variables

Tools

The MCP server exposes three tools to AI assistants.

lightfast_search

Search through workspace memory for relevant documents and observations.

Parameters

Example Request

json
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "quality"
  }
}
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "quality"
  }
}

Response Schema

typescript
{
  results: Array<{
    id: string;
    type: string;
    title: string;
    snippet: string;
    score: number;
    source: string;
    url: string;
  }>;
  meta: {
    total: number;
    latency: { total: number };
  };
}
{
  results: Array<{
    id: string;
    type: string;
    title: string;
    snippet: string;
    score: number;
    source: string;
    url: string;
  }>;
  meta: {
    total: number;
    latency: { total: number };
  };
}

lightfast_contents

Fetch full content for documents by their IDs.

Parameters

Example Request

json
{
  "name": "lightfast_contents",
  "arguments": {
    "ids": ["doc_abc123", "doc_def456"]
  }
}
{
  "name": "lightfast_contents",
  "arguments": {
    "ids": ["doc_abc123", "doc_def456"]
  }
}

Response Schema

typescript
{
  items: Array<{
    id: string;
    type: string;
    title: string;
    content: string;
    metadata: Record<string, unknown>;
  }>;
  missing: string[];
}
{
  items: Array<{
    id: string;
    type: string;
    title: string;
    content: string;
    metadata: Record<string, unknown>;
  }>;
  missing: string[];
}

lightfast_find_similar

Find content semantically similar to a given document or URL.

Parameters

Example Request

json
{
  "name": "lightfast_find_similar",
  "arguments": {
    "url": "https://github.com/org/repo/pull/123",
    "limit": 5,
    "threshold": 0.7
  }
}
{
  "name": "lightfast_find_similar",
  "arguments": {
    "url": "https://github.com/org/repo/pull/123",
    "limit": 5,
    "threshold": 0.7
  }
}

Response Schema

typescript
{
  results: Array<{
    id: string;
    type: string;
    title: string;
    snippet: string;
    score: number;
    source: string;
    url: string;
  }>;
  source: {
    id: string;
    title: string;
    type: string;
  };
}
{
  results: Array<{
    id: string;
    type: string;
    title: string;
    snippet: string;
    score: number;
    source: string;
    url: string;
  }>;
  source: {
    id: string;
    title: string;
    type: string;
  };
}

Error Responses

All tools return errors in the following format:

json
{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "requestId": "req_abc123"
}
{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "requestId": "req_abc123"
}

Related

• MCP Setup Guide - Configuration for Claude, Cursor, Codex
• POST /v1/search - REST API endpoint reference
• GitHub Repository - MCP server source code