# Connect Lampwick to your AI agent

> Lampwick runs an MCP server at https://app.lampwick.dev/mcp. Add it to Claude Code, Codex, Cursor or another client with a personal token.

The [MCP](https://modelcontextprotocol.io) server at `https://app.lampwick.dev/mcp` lets an AI agent read your issues, requests, logs and monitors and act on them. Every tool call is an [API](/docs/api/) request with your personal token, so the agent sees what you see.

## Requirements

- A personal API token, created under **API tokens** on **Account & security**. It starts with `lwp_`.
- An MCP client that supports the Streamable HTTP transport and a custom `Authorization` header.

The examples read the token from the `LAMPWICK_TOKEN` environment variable:

```bash
export LAMPWICK_TOKEN=YOUR_LAMPWICK_TOKEN
```

`YOUR_LAMPWICK_TOKEN` is your `lwp_…` token. Where a client can't read environment variables, paste it in place of `YOUR_LAMPWICK_TOKEN`.

## Add Lampwick to your client

Jump to: [Claude Code](#claude-code) · [Codex CLI](#codex-cli) · [Cursor](#cursor) · [VS Code](#vs-code) · [Gemini CLI](#gemini-cli) · [Zed](#zed) · [Cline](#cline) · [Claude API](#claude-api) · [OpenAI and xAI](#openai-responses-api-and-xai) · [Other clients](#other-clients)

### Claude Code

```bash
claude mcp add --transport http lampwick https://app.lampwick.dev/mcp --header "Authorization: Bearer $LAMPWICK_TOKEN"
```

Or share it with your team in the project's `.mcp.json`, where Claude Code fills in `${LAMPWICK_TOKEN}` from each person's environment:

```json
{
  "mcpServers": {
    "lampwick": {
      "type": "http",
      "url": "https://app.lampwick.dev/mcp",
      "headers": { "Authorization": "Bearer ${LAMPWICK_TOKEN}" }
    }
  }
}
```

### Codex CLI

In `~/.codex/config.toml`:

```toml
[mcp_servers.lampwick]
url = "https://app.lampwick.dev/mcp"
bearer_token_env_var = "LAMPWICK_TOKEN"
```

### Cursor

In `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "lampwick": {
      "url": "https://app.lampwick.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LAMPWICK_TOKEN}" }
    }
  }
}
```

### VS Code

In `.vscode/mcp.json`. VS Code asks for the token once and stores it:

```json
{
  "inputs": [
    { "type": "promptString", "id": "lampwick-token", "description": "lampwick API token", "password": true }
  ],
  "servers": {
    "lampwick": {
      "type": "http",
      "url": "https://app.lampwick.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:lampwick-token}" }
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add --transport http --header "Authorization: Bearer $LAMPWICK_TOKEN" lampwick https://app.lampwick.dev/mcp
```

### Zed

In your Zed settings:

```json
{
  "context_servers": {
    "lampwick": {
      "url": "https://app.lampwick.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_LAMPWICK_TOKEN" }
    }
  }
}
```

### Cline

In Cline's MCP settings:

```json
{
  "mcpServers": {
    "lampwick": {
      "type": "streamableHttp",
      "url": "https://app.lampwick.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_LAMPWICK_TOKEN" }
    }
  }
}
```

### Claude API

With the MCP connector of the Messages API, send the beta header `anthropic-beta: mcp-client-2026-09-15` and add to the request:

```json
{
  "mcp_servers": [
    { "type": "url", "url": "https://app.lampwick.dev/mcp", "name": "lampwick", "authorization_token": "YOUR_LAMPWICK_TOKEN" }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "lampwick" }
  ]
}
```

### OpenAI Responses API and xAI

Add Lampwick as a tool:

```json
{
  "type": "mcp",
  "server_label": "lampwick",
  "server_url": "https://app.lampwick.dev/mcp",
  "authorization": "YOUR_LAMPWICK_TOKEN",
  "require_approval": "always"
}
```

For xAI, leave out `require_approval`.

### Other clients

In other clients with a settings screen for MCP servers, add the URL `https://app.lampwick.dev/mcp` with the header `Authorization: Bearer YOUR_LAMPWICK_TOKEN`.

## Check that it works

Ask your agent "Which Lampwick projects can you see?". It calls `listProjects` and lists the projects of your teams.

## What you can ask

- "Which open issues in Acme Shop were first seen in the last 24 hours?"
- "What are the 10 slowest routes by p95 this week?"
- "Which uptime monitors are down right now?"
- "Which scheduled tasks are failing or missed their last run?"
- "Show the error logs from the last hour that mention timeout, then resolve issue #42."

## What the agent can do

- Each API operation is a tool named after its `operationId` (`listIssues`, `getIssue`, `updateIssue`, …), with its path, query and body fields as arguments. Validation, access and owner rules are those of the API; an error comes back with `isError: true`.
- Read tools carry `readOnlyHint`; deletes and `rotateProjectToken` carry `destructiveHint`, so clients that honor the hints ask before running them.
- Not tools: token management, logging out, push devices, team invites, members and roles, and creating, changing or deleting status pages and notices.
- When the client connects, Lampwick tells the agent its conventions: durations in microseconds, the `range` values, `id` versus `ref`, and where to start.

## Protocol details

| Topic | Value |
|---|---|
| Endpoint | `POST https://app.lampwick.dev/mcp` |
| Transport | Streamable HTTP, stateless: no sessions, no server-initiated stream (`GET /mcp` gives `405`) |
| Authentication | `Authorization: Bearer lwp_…` (a personal token; a dashboard session doesn't count) |
| Protocol versions | `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Browsers | A request with a cross-site `Origin` gets `403` |
| Batches | Up to 50 messages; larger batches get one JSON-RPC error `-32600` |

## Troubleshooting

| What you see | Cause and fix |
|---|---|
| `401` or an authorization error | The `Authorization` header is missing, or the token is wrong, expired or revoked. Create a new token on **Account & security**. |
| `405` | The client tried `GET /mcp` for a stream. Lampwick only takes `POST`; pick the Streamable HTTP transport. |
| A project is missing | The token only sees the teams of its account. Ask an owner to invite you to the team. |
| A tool returns `403` | That action is for team owners. |