index.md

Lightsage MCP

Choose a client and connect Lightsage MCP to coding agents and MCP-capable tools.

Lightsage MCP gives AI agents direct access to the Lightsage public API through the Model Context Protocol. Use it when you want an agent to list prompts, inspect API Performance configuration, create eval runs, retrieve results, or manage Lightsage resources without shelling out to the Lightsage CLI.

Install by client

Choose the client you want to configure. Each guide connects the client to https://mcp.lightsage.com/mcp.

Lightsage MCP supports two authentication methods:

OAuth — hosted connector surfaces (ChatGPT, Claude web/Desktop) sign in with your Lightsage account and pick an organization. No API key required.
X-Lightsage-Api-Key header — coding agents and CLI-based clients send a Lightsage API key from the dashboard.

Clients Supported:

ChatGPT Add Lightsage in developer mode with its public OAuth client.
Claude Add Lightsage as a custom connector in Claude web or Desktop with OAuth.
Claude Code Add Lightsage as a remote HTTP MCP server with a custom auth header.
Codex Configure Lightsage MCP in ~/.codex/config.toml.
Cursor Add Lightsage MCP to your global or project Cursor MCP config.
Gemini CLI Add Lightsage MCP to Gemini CLI with a streamable HTTP server.
GitHub Copilot Configure Lightsage MCP for GitHub Copilot in VS Code or Copilot CLI.
Kilo Configure Lightsage MCP as a remote server in Kilo.
OpenCode Configure Lightsage as a remote MCP server in opencode.json.

Run the local package

For clients that require a local stdio process, run the published MCP package:

export LIGHTSAGE_API_KEY="ls_cli_your_api_key"
npx -y @lightsage/mcp start --lightsage-api-key-auth "$LIGHTSAGE_API_KEY"

Verify the connection

After configuring a client, start with a read-only prompt:

Use the Lightsage MCP server to check my Lightsage auth status.

Then try a low-risk API Performance prompt:

Use Lightsage MCP to list my API Performance targets and summarize the available coding agents.

For GEO outreach research, ask for URL-level citation data:

Use Lightsage MCP to list the 20 most cited URLs on ChatGPT over the last 30 days, including each citation count.

If the client cannot list tools, confirm the endpoint is reachable:

curl -i https://mcp.lightsage.com/mcp

OAuth-enabled clients receive a 401 Unauthorized challenge before sign-in. The response must include:

WWW-Authenticate: Bearer resource_metadata="https://mcp.lightsage.com/.well-known/oauth-protected-resource/mcp"

Troubleshooting

Problem	Fix
The client connects but tool calls return `401`	For header auth, confirm the client is sending `X-Lightsage-Api-Key` with a valid Lightsage API key. For OAuth, re-run the sign-in flow so the client gets a fresh token.
A ChatGPT custom connector fails during OAuth	Follow the ChatGPT manual OAuth setup. Do not use automatic client registration.
The client has no custom header field	Use OAuth instead (ChatGPT, Claude web/Desktop), or pick a client that can send custom headers.
The client only supports local stdio MCP	Use a local stdio-to-HTTP bridge that forwards to the hosted Lightsage MCP endpoint.
Too many tools appear in context	Use the hosted deployment's default dynamic mode, which exposes discovery tools first.