layven-mcp

# Layven MCP Server

Layven is a shared drive your agents mount over MCP. Every write is versioned, every action is attributed to the agent that made it, and anything can be rolled back.

One config block, no agent code changes. Hosted at `https://api.layven.io/mcp`.

Documents Layven MCP server **1.0.2**.

---

## Quick start

```
claude mcp add --transport http layven https://api.layven.io/mcp --header "Authorization: Bearer agd_your_agent_token"
```

1. Get a token at [layven.io](https://layven.io): open the console, go to Agents, create one. The secret is shown once.
2. Restart your client.
3. Ask your agent: "list my Layven workspaces".

The point of the product shows up on the second connection. Create a second token, connect a different tool with it, and have that tool read the file the first one just wrote. Both agents see the same drive, and the activity feed says which one did what. Walkthrough: [examples/two-agent-handoff.md](examples/two-agent-handoff.md).

---

## Connect your client

### Claude Code

```
claude mcp add --transport http layven https://api.layven.io/mcp --header "Authorization: Bearer agd_your_agent_token"
```

### Claude.ai custom connector

Paste `https://api.layven.io/mcp` and authenticate with OAuth. That UI has no custom-header field, which is why OAuth exists.

### ChatGPT

Same as Claude.ai: paste `https://api.layven.io/mcp` and authenticate with OAuth.

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "layven": {
      "url": "https://api.layven.io/mcp",
      "headers": {
        "Authorization": "Bearer agd_your_agent_token"
      }
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.layven]
url = "https://api.layven.io/mcp"
http_headers = { "Authorization" = "Bearer agd_your_agent_token" }
```

### Gemini (`~/.gemini/settings.json`)

Same JSON as Cursor, but the key is `httpUrl` instead of `url`, because Gemini reads `url` as an SSE endpoint.

```json
{
  "mcpServers": {
    "layven": {
      "httpUrl": "https://api.layven.io/mcp",
      "headers": {
        "Authorization": "Bearer agd_your_agent_token"
      }
    }
  }
}
```

### Generic MCP JSON

```json
{
  "mcpServers": {
    "layven": {
      "url": "https://api.layven.io/mcp",
      "headers": {
        "Authorization": "Bearer agd_your_agent_token"
      }
    }
  }
}
```

---

## Authentication

There are two ways in, and both resolve to the same token record, so permissions, revocation and the audit trail are identical either way.

**Static bearer token.** Send `Authorization: Bearer agd_...` on every request. Create it in the console; the secret is shown once.

**OAuth 2.1**, for clients whose UI has no custom-header field:

| | |
|---|---|
| Authorization server | `https://api.layven.io` |
| Protected resource metadata | `https://api.layven.io/.well-known/oauth-protected-resource/mcp` |
| Resource | `https://api.layven.io/mcp` |
| Dynamic client registration | Supported |
| Client secret expiry | Does not expire |

Consent mints an ordinary token, which you can see and revoke in the console like any other.

---

## Transport

- `POST https://api.layven.io/mcp`, Streamable HTTP, stateless.
- Every POST is fully independent. No session id, no session resumption, no separate SSE endpoint, no stdio.
- GET and DELETE return HTTP 405 with exactly this body:
  ```json
  {"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed (stateless)"},"id":null}
  ```
- Required request headers: `Content-Type: application/json` and `Accept: application/json, text/event-stream`. Both media types must be present in `Accept` or the server returns 406.
- Responses come back as `Content-Type: text/event-stream`.
- `MCP-Protocol-Version` is optional. If present it must be one of `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`, otherwise the server returns HTTP 400.
- Capabilities: `tools` only. No resources, no prompts.
- Server identity on `initialize`: name `Layven`, version `1.0.2`, website `https://layven.io`.

---

## Tools

Every tool takes an optional `workspace`, the workspace slug. A token granted exactly one workspace may omit it. `list` with no `workspace` fans out over every workspace the token can reach.

| Tool | Access | Does | Key arguments |
|---|---|---|---|
| [`list`](#list) | `ro` | List a folder, or find files by path substring | `path`, `recursive`, `q`, `limit` |
| [`read`](#read) | `ro` | Read a file at the current or an older version | `path`, `version` |
| [`grep`](#grep) | `ro` | Search file contents with an RE2 pattern | `pattern`, `prefix`, `context_lines`, `max_matches` |
| [`history`](#history) | `ro` | List one file's versions, newest first | `path`, `limit`, `cursor` |
| [`activity`](#activity) | `ro` | List what changed and which agent changed it | `since`, `path_prefix`, `limit` |
| [`write`](#write) | `rw` | Create or replace a file with inline content | `path`, `content`, `encoding`, `expected_version` |
| [`edit`](#edit) | `rw` | Apply string replacements to an existing text file | `path`, `edits`, `expected_version` |
| [`move`](#move) | `rw` | Move or rename a file | `from`, `to`, `overwrite` |
| [`delete`](#delete) | `rw` | Tombstone a file, recoverable with `restore` | `path`, `expected_version` |
| [`restore`](#restore) | `rw` | Restore a file to a version, or a folder to a timestamp | `path` + `to_version`, or `prefix` + `at` |
| [`lock`](#lock) | `rw` | Take a 5-minute advisory lock on a path | `path` |
| [`unlock`](#unlock) | `rw` | Release a lock this token holds | `path` |
| [`request_upload`](#request_upload) | `rw` | Start a large-file upload, returns a presigned PUT URL | `path`, `size`, `expected_version` |
| [`finalize_upload`](#finalize_upload) | `rw` | Commit an uploaded file as a new version | `upload_id` |

Only `delete` is annotated destructive, and it writes a tombstone version that `restore` brings back. `write`, `delete`, `lock` and `unlock` are annotated idempotent; `edit`, `move`, `restore`, `request_upload` and `finalize_upload` are not. No tool reaches outside Layven.

`NOT_FOUND` (unresolvable workspace), `PERMISSION_DENIED`, `RATE_LIMITED` and `INTERNAL` can come back from any tool, so the `Errors` line under each tool below names what is specific to that tool.

#### `list`

List a folder, or search every granted workspace for paths matching a substring.

**Arguments**

```
workspace?        string    workspace slug; omit to fan out over every granted workspace
path              string    default "" (workspace root)
recursive         boolean   default false
include_deleted   boolean   default false
limit             integer   1..1000, default 500, applied per workspace
cursor?           string    opaque; requires an explicit workspace
q?                string    1..1024 chars, case-insensitive substring of the full path; implies recursive
```

**Returns**

```json
{
  "results": [
    {
      "workspace": { "id": "...", "slug": "research" },
      "entries": [
        {
          "path": "notes/todo.md",
          "type": "file",
          "size": 1284,
          "version": 7,
          "modified_at": "2026-08-05T09:12:44Z",
          "modified_by_label": "research-agent",
          "by_actor": "agent",
          "deleted": true
        }
      ],
      "next_cursor": "..."
    }
  ]
}
```

`type` is `"file"` or `"folder"`. `size`, `version`, `modified_at`, `modified_by_label`, `by_actor` and `deleted` are optional per entry.

**Errors:** `INVALID_PATH`.

**Notes**

- `results` is always an array of per-workspace blocks, even when the token is granted exactly one workspace. Do not write a client that expects a bare `entries` array.
- Passing `cursor` while fanning out returns `INVALID_PATH` with `reason: "cursor_requires_workspace"`. Pin the workspace before you paginate.
- Folders are synthesized from path prefixes. There are no folder records to create or delete.

#### `read`

Read a file, either the current version or an older one.

**Arguments**

```
workspace?   string
path         string
version?     integer   defaults to the current version
```

**Returns**, inline, when the raw size is 262144 bytes or less and the mime type is text:

```json
{
  "path": "notes/todo.md",
  "version": 7,
  "size": 1284,
  "mime_type": "text/markdown",
  "encoding": "utf8",
  "content": "..."
}
```

**Returns**, for anything larger or binary:

```json
{
  "path": "datasets/corpus.tar.gz",
  "version": 3,
  "size": 431912448,
  "mime_type": "application/gzip",
  "download_url": "https://...",
  "url_expires_at": "2026-08-05T09:27:00Z"
}
```

**Errors:** `NOT_FOUND` (with `deleted: true` and `last_version` when the path is tombstoned), `INVALID_PATH`.

**Notes**

- The response shape switches on size and mime type, not on a flag you pass. Above 256 KiB, or for any non-text file, you get a `download_url` valid for 15 minutes instead of inline content. Handle both shapes.

#### `grep`

Search file contents with a regular expression.

**Arguments**

```
workspace?       string
path?            string    search a single file
prefix?          string    search one folder; omit both path and prefix to search the whole workspace
pattern          string    min 1 char, RE2 syntax
case_sensitive   boolean   default false
context_lines    integer   0..10, default 2
max_matches      integer   1..200, default 50
```

**Returns**

```json
{
  "matches": [
    {
      "path": "notes/todo.md",
      "line": 42,
      "text": "TODO: rotate the staging token",
      "before": ["..."],
      "after": ["..."]
    }
  ],
  "files_scanned": 128,
  "files_skipped_binary": 3,
  "files_skipped_too_large": 0,
  "truncated": false
}
```

**Errors:** `INVALID_PATTERN`, `INVALID_PATH`.

**Notes**

- Patterns are RE2, so there are no backreferences and no lookaround. An invalid pattern returns `INVALID_PATTERN`.
- Matches are found within single lines only. A pattern spanning a newline will never match.
- One entry per matching line, lik