MCP Server

Lightfast supports two MCP connection modes:

• Hosted OAuth MCP for user-connected clients. This is recommended when your client supports remote MCP and OAuth.
• @lightfastai/mcp stdio for local, CI, and API-key based clients.

Both modes expose the same policy-derived Lightfast tools.

Hosted OAuth MCP

Use the hosted MCP resource when a client can connect to a remote MCP server:

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

In local development, the resource URL is:

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 OAuth flow creates a user-connected grant bound to the selected organization. You can review or revoke grants from MCP settings.

Local stdio MCP

Use the stdio package when your MCP client expects a local command or when you need API-key automation. Run directly with npx:

bash
npx @lightfastai/mcp --api-key lf_...
npx @lightfastai/mcp --api-key lf_...

Or install globally:

bash
npm install -g @lightfastai/mcp
lightfast-mcp --api-key lf_...
npm install -g @lightfastai/mcp
lightfast-mcp --api-key lf_...

Configuration

Choose your AI assistant and add the configuration:

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

json
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

Add to .mcp.json in your project root:

json
{
  "mcpServers": {
    "lightfast": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}
{
  "mcpServers": {
    "lightfast": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}

Or use the CLI:

bash
claude mcp add lightfast --scope project -- npx -y @lightfastai/mcp
claude mcp add lightfast --scope project -- npx -y @lightfastai/mcp

For global (user-level) configuration, add to ~/.claude.json or use --scope user.

Cursor

Add to .cursor/mcp.json in your project root:

json
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "lf_..."
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

toml
[mcp_servers.lightfast]
command = "npx"
args = ["-y", "@lightfastai/mcp"]

[mcp_servers.lightfast.env]
LIGHTFAST_API_KEY = "lf_..."
[mcp_servers.lightfast]
command = "npx"
args = ["-y", "@lightfastai/mcp"]

[mcp_servers.lightfast.env]
LIGHTFAST_API_KEY = "lf_..."

Available Tools

Once configured, your AI assistant has access to the Lightfast MCP tools selected by the public API contract policy.

lightfast_system_health

Check whether the Lightfast MCP connection is authenticated and reachable.

Required scope: mcp:system:read

Parameters: none.

Response includes status, timestamp, and version.

lightfast_signals_create

Create a signal in the connected organization.

Required scope: mcp:signals:write

Requires the grant to be bound to the selected organization.

Response includes the new signal_<uuid> id, status: "queued", and visibilityScope: "user".

lightfast_signals_get

Get a visible signal by id from the connected organization.

Required scope: mcp:signals:read

Requires the grant to be bound to the selected organization.

Response includes id, input, status, classification, visibilityScope, createdAt, and updatedAt. classification is null until available.

Usage Examples

Once configured, you can ask your AI assistant questions like:

• "Create a Lightfast signal for this follow-up"
• "Check the status of this signal"
• "Confirm my Lightfast MCP connection is healthy"

The AI assistant will automatically call the relevant Lightfast MCP tool when needed.

CLI Options

bash
npx @lightfastai/mcp [options]

Options:
  --api-key <key>    Lightfast API key (or set LIGHTFAST_API_KEY env var)
  --base-url <url>   API base URL (default: https://lightfast.ai)
  --help, -h         Show help message
  --version, -v      Show version
npx @lightfastai/mcp [options]

Options:
  --api-key <key>    Lightfast API key (or set LIGHTFAST_API_KEY env var)
  --base-url <url>   API base URL (default: https://lightfast.ai)
  --help, -h         Show help message
  --version, -v      Show version

Environment Variables

Instead of passing --api-key, you can set the environment variable:

bash
export LIGHTFAST_API_KEY=lf_...
npx @lightfastai/mcp
export LIGHTFAST_API_KEY=lf_...
npx @lightfastai/mcp

This is especially useful in MCP configurations where you don't want to hardcode the key:

json
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "${LIGHTFAST_API_KEY}"
      }
    }
  }
}
{
  "mcpServers": {
    "lightfast": {
      "command": "npx",
      "args": ["-y", "@lightfastai/mcp"],
      "env": {
        "LIGHTFAST_API_KEY": "${LIGHTFAST_API_KEY}"
      }
    }
  }
}

Troubleshooting

Server not connecting

1. Verify your API key is valid and starts with lf_
2. Check that Node.js >= 18 is installed
3. Restart your AI assistant after configuration changes

Tools not appearing

1. Ensure the MCP server is running (check logs)
2. Verify the configuration file is in the correct location
3. For Claude Code, run /mcp to check server status

Permission errors

1. Check that your API key has access to the workspace
2. Confirm the organization has searchable memory available
3. Regenerate the API key if it was revoked or rotated

Next Steps

• Use the SDK in your application
• View hosted OAuth MCP source on GitHub
• View local stdio MCP source on GitHub