> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://app.lightsage.com/settings/api).

<CardGroup cols={3}>
  <Card title="ChatGPT" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/openai.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=e6b743c87b5319e412e8acfbeb49a070" href="/docs/mcp-reference/chatgpt" width="24" height="24" data-path="images/mcp-icons/openai.svg">
    Add Lightsage in developer mode with its public OAuth client.
  </Card>

  <Card title="Claude" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/claude.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=e6c93e69b2742291b8d22af777f46212" href="/docs/mcp-reference/claude" width="24" height="24" data-path="images/mcp-icons/claude.svg">
    Add Lightsage as a custom connector in Claude web or Desktop with OAuth.
  </Card>

  <Card title="Claude Code" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/claude.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=e6c93e69b2742291b8d22af777f46212" href="/docs/mcp-reference/claude-code" width="24" height="24" data-path="images/mcp-icons/claude.svg">
    Add Lightsage as a remote HTTP MCP server with a custom auth header.
  </Card>

  <Card title="Codex" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/codex.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=2301c82c71c58f388327b69352eab760" href="/docs/mcp-reference/codex" width="24" height="24" data-path="images/mcp-icons/codex.svg">
    Configure Lightsage MCP in `~/.codex/config.toml`.
  </Card>

  <Card title="Cursor" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/cursor.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=95c4200ad125ebb58138446aa3d48a65" href="/docs/mcp-reference/cursor" width="24" height="24" data-path="images/mcp-icons/cursor.svg">
    Add Lightsage MCP to your global or project Cursor MCP config.
  </Card>

  <Card title="Gemini CLI" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/gemini.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=e4c7fad7d2db4e31be9ebc394c5034ec" href="/docs/mcp-reference/gemini-cli" width="65" height="65" data-path="images/mcp-icons/gemini.svg">
    Add Lightsage MCP to Gemini CLI with a streamable HTTP server.
  </Card>

  <Card title="GitHub Copilot" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/github-copilot.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=e9605a8dab5a3d0132a410d565e5669c" href="/docs/mcp-reference/github-copilot" width="24" height="24" data-path="images/mcp-icons/github-copilot.svg">
    Configure Lightsage MCP for GitHub Copilot in VS Code or Copilot CLI.
  </Card>

  <Card title="Kilo" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/kilo.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=3096cf79a5c08fe07f6698116620fc1c" href="/docs/mcp-reference/kilo" width="32" height="32" data-path="images/mcp-icons/kilo.svg">
    Configure Lightsage MCP as a remote server in Kilo.
  </Card>

  <Card title="OpenCode" icon="https://mintcdn.com/sapient-14d4e375/qxhkraBSjyCB4qIr/images/mcp-icons/opencode.svg?fit=max&auto=format&n=qxhkraBSjyCB4qIr&q=85&s=115b57370743754113604f7034c13a0b" href="/docs/mcp-reference/opencode" width="240" height="300" data-path="images/mcp-icons/opencode.svg">
    Configure Lightsage as a remote MCP server in `opencode.json`.
  </Card>
</CardGroup>

## Run the local package

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

```bash theme={null}
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:

```text theme={null}
Use the Lightsage MCP server to check my Lightsage auth status.
```

Then try a low-risk API Performance prompt:

```text theme={null}
Use Lightsage MCP to list my API Performance targets and summarize the available coding agents.
```

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

```bash theme={null}
curl -i https://mcp.lightsage.com/mcp
```

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

```text theme={null}
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](/docs/mcp-reference/chatgpt). 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.                                                                                    |

## Related docs

* [CLI Reference](/docs/cli-reference) - install and authenticate the Lightsage CLI
* [Build an MCP server for direct coding agent access](/docs/guides/mcp-servers) - learn how MCP changes agent recommendations
* [API Performance runs](/docs/cli-reference/api-performance-runs) - inspect runs from the CLI