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]

Option	Type	Default	Description
`--api-key`	`string`	`$LIGHTFAST_API_KEY`	Lightfast API key
`--base-url`	`string`	`https://lightfast.ai`	API base URL
`--help, -h`	-	-	Show help message
`--version, -v`	-	-	Show version

Environment Variables

Variable	Description
`LIGHTFAST_API_KEY`	API key (alternative to `--api-key` flag)

Tools

The MCP server exposes the following tool to AI assistants.

lightfast_search

Search through connected tools for relevant decisions and observations.

Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

query*string

The search query text to find relevant documents

Length1 <= length

limit?integer

Maximum number of results to return (1-100, default: 10)

Default10

Range1 <= value <= 100

offset?integer

Result offset for pagination (default: 0)

Default0

Range0 <= value <= 9007199254740991

mode?string

Search quality mode: 'fast' (vector scores only), 'balanced' (Cohere rerank)

Default"balanced"

Value in"fast" | "balanced"

sources?array<>

Filter by source provider (e.g. ["github", "linear", "sentry"])

types?array<>

Filter by entity type (e.g. ["pull_request", "issue", "error"])

after?string

Only include results after this ISO 8601 datetime

Formatdate-time

before?string

Only include results before this ISO 8601 datetime

Formatdate-time

Response Body

`application/json`

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Search query text
`limit`	`number`	No	`10`	Max results (1–100)
`offset`	`number`	No	`0`	Pagination offset
`mode`	`"fast" \| "balanced"`	No	`"balanced"`	`fast` = vector scores only, `balanced` = Cohere rerank
`sources`	`string[]`	No	—	Filter by provider (e.g. `["github", "linear"]`)
`types`	`string[]`	No	—	Filter by entity type (e.g. `["pull_request", "issue"]`)
`after`	`string`	No	—	ISO 8601 datetime lower bound
`before`	`string`	No	—	ISO 8601 datetime upper bound

Example Request

json
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "balanced",
    "sources": ["github"],
    "after": "2024-01-01T00:00:00Z"
  }
}
{
  "name": "lightfast_search",
  "arguments": {
    "query": "how does authentication work",
    "limit": 5,
    "mode": "balanced",
    "sources": ["github"],
    "after": "2024-01-01T00:00:00Z"
  }
}

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

Error Code	Description
`UNAUTHORIZED`	Invalid or missing API key
`VALIDATION_ERROR`	Invalid parameters
`NOT_FOUND`	Resource not found
`INTERNAL_ERROR`	Server error

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

MCP Server Reference

Installation

CLI Options

Environment Variables

Tools

lightfast_search

Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

Example Request

Error Responses

Related

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`