MCP Server Reference

Lightfast exposes MCP tools through the hosted OAuth resource server and the @lightfastai/mcp local stdio package.

Hosted OAuth resource:

text
https://mcp.lightfast.ai/mcp
https://mcp.lightfast.ai/mcp

Local development resource:

text
https://[<wt>.]mcp.lightfast.localhost/mcp
https://[<wt>.]mcp.lightfast.localhost/mcp

[<wt>.] is an optional local worktree prefix. Use https://mcp.lightfast.localhost/mcp in the primary worktree, or a prefixed URL such as https://remote-mcp.mcp.lightfast.localhost/mcp in a secondary worktree.

The @lightfastai/mcp package remains available for API-key stdio clients.

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 policy-derived tools to AI assistants. Hosted OAuth clients must request the scope listed for each tool.

lightfast_system_health

Check whether the connection is authenticated and reachable.

Field	Value
Required scope	`mcp:system:read`
Requires selected organization	No

Parameters: none.

Response:

json
{
  "status": "ok",
  "timestamp": "2026-06-01T00:00:00.000Z",
  "version": "0.1.0"
}
{
  "status": "ok",
  "timestamp": "2026-06-01T00:00:00.000Z",
  "version": "0.1.0"
}

lightfast_signals_create

Create a signal in the connected organization.

Field	Value
Required scope	`mcp:signals:write`
Requires selected organization	Yes

Parameter	Type	Required	Description
`input`	`string`	Yes	Signal text. Trimmed, 1-4000 characters.

Response:

json
{
  "id": "signal_00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "visibilityScope": "user"
}
{
  "id": "signal_00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "visibilityScope": "user"
}

lightfast_signals_get

Get a visible signal by id from the connected organization.

Field	Value
Required scope	`mcp:signals:read`
Requires selected organization	Yes

Parameter	Type	Required	Description
`id`	`string`	Yes	Signal id in `signal_<uuid>` format.

Response:

json
{
  "id": "signal_00000000-0000-0000-0000-000000000000",
  "input": "Follow up with Ada about the launch review",
  "status": "classified",
  "classification": {
    "disposition": "actionable",
    "title": "Launch review follow-up",
    "summary": "Follow up with Ada about the launch review.",
    "kind": "follow_up",
    "nextAction": "Contact Ada",
    "priority": "normal",
    "rationale": "The input asks for a follow-up action.",
    "confidence": 0.92,
    "routing": {
      "visibility": {
        "scope": "user",
        "rationale": "The request is user-scoped."
      },
      "review": {
        "required": false,
        "reason": null,
        "rationale": null
      },
      "routes": {
        "people": {
          "shouldRun": false,
          "confidence": 0.4,
          "rationale": "No people search is required."
        }
      }
    }
  },
  "visibilityScope": "user",
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}
{
  "id": "signal_00000000-0000-0000-0000-000000000000",
  "input": "Follow up with Ada about the launch review",
  "status": "classified",
  "classification": {
    "disposition": "actionable",
    "title": "Launch review follow-up",
    "summary": "Follow up with Ada about the launch review.",
    "kind": "follow_up",
    "nextAction": "Contact Ada",
    "priority": "normal",
    "rationale": "The input asks for a follow-up action.",
    "confidence": 0.92,
    "routing": {
      "visibility": {
        "scope": "user",
        "rationale": "The request is user-scoped."
      },
      "review": {
        "required": false,
        "reason": null,
        "rationale": null
      },
      "routes": {
        "people": {
          "shouldRun": false,
          "confidence": 0.4,
          "rationale": "No people search is required."
        }
      }
    }
  },
  "visibilityScope": "user",
  "createdAt": "2026-06-01T00:00:00.000Z",
  "updatedAt": "2026-06-01T00:00:00.000Z"
}

status is one of queued, processing, classified, or failed. classification is null until classification is available. visibilityScope is one of user, team, or needs_review.

Example Request

json
{
  "name": "lightfast_signals_create",
  "arguments": {
    "input": "Follow up with Ada about the launch review"
  }
}
{
  "name": "lightfast_signals_create",
  "arguments": {
    "input": "Follow up with Ada about the launch review"
  }
}

Error Responses

HTTP authentication failures return an OAuth bearer error response:

json
{
  "error": "invalid_token",
  "error_description": "Bearer token is invalid."
}
{
  "error": "invalid_token",
  "error_description": "Bearer token is invalid."
}

Tool execution failures are returned as MCP tool results with isError: true and a text message.

Error Code	Description
`missing_token`	OAuth bearer token is missing
`invalid_token`	OAuth bearer token is invalid or expired
`insufficient_scope`	Token is missing the scope required by the tool
`invalid_input`	Tool parameters failed schema validation
`not_found`	Requested signal is not visible or does not exist
`org_access_denied`	The user or grant no longer has access to the selected organization
`upstream_error`	A Lightfast upstream service returned an error
`unsupported_tool`	The requested MCP tool is not supported

MCP Setup Guide - Configuration for hosted OAuth and stdio clients
Hosted OAuth MCP source
Local stdio MCP source

MCP Server Reference

Installation

CLI Options

Environment Variables

Tools

lightfast_system_health

lightfast_signals_create

lightfast_signals_get

Example Request

Error Responses

Related

On this page