# MCP server

Connect Claude, Cursor, VS Code and other MCP clients to your workspace and ask it questions.

Lornos runs a [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI assistant or coding agent can ask your workspace questions and read the passages behind the answers. It uses the same API keys as the [API](https://lornos.dev/docs/api.md), and it reads only the workspace the key belongs to.

## Server address

```text
https://lornos.dev/mcp
```

The server speaks the Streamable HTTP transport and answers each request with JSON. It keeps no session between requests.

## Authentication

Create an [API key](https://lornos.dev/docs/api-keys.md) and send it on every request:

```text
Authorization: Bearer lrn_…
```

The key decides everything the server can reach:

- **The workspace.** Every tool reads the workspace the key was created in. No tool takes a workspace name or ID, so a client can't point it at another workspace.
- **The tools.** A key with the `chat` scope sees `ask` and `search`. A key with the `sources` scope sees `list_sources` and `get_source`. A key with both sees all four.
- **Revoking.** A revoked or expired key gets `401` on its next request.

Give an assistant its own key, with only the scopes it needs, so you can revoke it without touching your app.

## Connect a client

Replace `lrn_…` with your key in each example.

### Claude Code

```bash
claude mcp add --transport http lornos https://lornos.dev/mcp --header "Authorization: Bearer lrn_…"
```

### Cursor

In `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "lornos": {
      "url": "https://lornos.dev/mcp",
      "headers": { "Authorization": "Bearer lrn_…" }
    }
  }
}
```

### VS Code

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "lornos": {
      "type": "http",
      "url": "https://lornos.dev/mcp",
      "headers": { "Authorization": "Bearer lrn_…" }
    }
  }
}
```

### Other clients

Any client that supports remote servers over HTTP with a custom header works. Clients that only connect through an OAuth sign-in can't connect yet.

## Tools

| Tool | Scope | What it does |
|---|---|---|
| `ask` | `chat` | Answers a question from your documents and cites passages by chunk ID, for example `[refunds.md#2]`. |
| `search` | `chat` | Returns the passages that best match a query, each with its chunk ID and file, so the assistant can read the evidence itself. Up to 10 passages; 5 by default. |
| `list_sources` | `sources` | Lists your documents with their indexing status and passage counts. |
| `get_source` | `sources` | Shows one document by its source ID, including why indexing failed if it did. |

`ask` follows the same rules as every answer: it cites only passages retrieved for that question, and when nothing in your documents covers it, it says so instead of guessing. See [Citations](https://lornos.dev/docs/citations.md).

## What the MCP server doesn't do

Every tool only reads. These stay in the console and the [API](https://lornos.dev/docs/api.md):

- uploading, re-indexing and deleting sources;
- creating or revoking API keys;
- adding or removing members and changing roles;
- workspace settings, usage and limits.

Nothing outside your workspace is reachable through MCP.

## Limits and usage

Each `ask` and each `search` counts as one question toward your workspace's limits, the same limits the playground and the API share. Over a limit, the tool returns a message saying when to try again. See [Limits](https://lornos.dev/docs/limits.md).

Both tools show on the **Usage** page in the console, marked **MCP** with the key's name: `ask` as a question, `search` as a search. `list_sources` and `get_source` aren't counted.

## Check the connection

To check a key without a client, list its tools:

```bash
curl "https://lornos.dev/mcp" \
  -H "Authorization: Bearer lrn_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A valid key returns the tools its scopes allow. A missing, revoked or expired key returns `401`.