# MCP server

> Connect Claude, Cursor, VS Code or any MCP client to a Lydie workspace, hosted or on your own computer.

Lydie's MCP server lets AI assistants search, read and edit your pages. It uses the same operations
as the REST API, so an agent can do what you can do in the app.

```text
https://api.lydie.co/mcp
```

It speaks Streamable HTTP and answers each request with JSON. It keeps no state between requests.

## Connect a client

Most clients sign in with OAuth: they open Lydie, you pick a workspace and approve. To use an
[API token](https://developers.lydie.co/authentication.md) instead, add an `Authorization: Bearer lyd_pat_…` header to the
configs below. **Settings → Agents & API → Hosted MCP** in the app shows these snippets with your
token filled in.

### Claude Code

```bash
claude mcp add --transport http lydie https://api.lydie.co/mcp
```

### Cursor

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "lydie": { "url": "https://api.lydie.co/mcp" }
  }
}
```

### VS Code

```json title=".vscode/mcp.json"
{
  "servers": {
    "lydie": { "type": "http", "url": "https://api.lydie.co/mcp" }
  }
}
```

### Claude Desktop

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "lydie": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.lydie.co/mcp"]
    }
  }
}
```

## Tools

The server lists a small set of agent-sized tools: `search`, `list_docs`, `fetch_doc`,
`create_doc`, `update_doc`, the database tools such as `query_database` and `write_database_rows`,
and the history tools. [MCP tools](https://developers.lydie.co/mcp/tools.md) lists them all with their inputs.

Two more tools reach everything else. `describe_operation` returns an operation's input and output
schema, and `run_operation` runs it by id. These cover teamspaces, sharing, publishing,
notifications and the fine-grained database operations.

Good habits for agents:

- Find pages with `search` or `list_docs`, then read them with `fetch_doc`.
- Change a body with `update_doc` and `edits` (exact `oldStr`/`newStr` pairs), not by sending the
  whole page. Pass the `expectedVersion` from `fetch_doc`.
- Read `warnings` in the result: an edit that did not match exactly once was skipped.

## Undo what an agent did

Each connection is one history session. `list_session_changes` shows what the agent changed, and
`undo_session` reverts all of it in one step. See [Agent changes and undo](https://developers.lydie.co/agent-history.md).

## On your own computer

The desktop app can run a local MCP server for a workspace opened from a folder. No account or
network is needed, and every change is written to the Markdown files in that folder. Turn it on
under **Settings → Agents & API → On this computer**. It listens on `127.0.0.1` and needs the token
from the token file shown there.

The tools are the same as on the hosted server. The `lydie` command-line tool in the
[open-source client](https://github.com/lydiehq/lydie/tree/v2/packages/cli) runs the same server
with `lydie mcp --vault ~/Notes`, or `--stdio` for clients that start the server themselves.