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 five tools to AI assistants.

lightfast_search

Search through workspace memory for relevant documents and observations.

Parameters & Response

Filters object structure:

• sourceTypes: string[] - Source types to include (e.g., ["github", "linear"])
• observationTypes: string[] - Observation types to include (e.g., ["commit", "issue"])
• actorNames: string[] - Actor names to filter by (e.g., ["@sarah", "@mike"])
• dateRange: object - Date range filter with start and end ISO datetime strings

Example Request

json
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "thorough",
    "filters": {
      "sourceTypes": ["github"],
      "dateRange": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-12-31T23:59:59Z"
      }
    }
  }
}
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "thorough",
    "filters": {
      "sourceTypes": ["github"],
      "dateRange": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-12-31T23:59:59Z"
      }
    }
  }
}

lightfast_contents

Fetch full content for documents by their IDs.

Parameters & Response

Example Request

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

lightfast_find_similar

Find content semantically similar to a given document or URL.

Parameters & Response

Note: Filters have the same structure as lightfast_search.

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
  }
}

lightfast_graph

Traverse the relationship graph from a starting observation. Returns connected observations with relationship edges. Supports depth control (1-3) and relationship type filtering.

Parameters & Response

Example Request

json
{
  "name": "lightfast_graph",
  "arguments": {
    "id": "obs_abc123",
    "depth": 2
  }
}
{
  "name": "lightfast_graph",
  "arguments": {
    "id": "obs_abc123",
    "depth": 2
  }
}

lightfast_related

Find observations directly connected to a given observation via relationships. Returns related events grouped by source system with relationship types and directions.

Parameters & Response

Example Request

json
{
  "name": "lightfast_related",
  "arguments": {
    "id": "obs_abc123"
  }
}
{
  "name": "lightfast_related",
  "arguments": {
    "id": "obs_abc123"
  }
}

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