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: 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.

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`)

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

Codex (`~/.codex/config.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.

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

Generic MCP 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:

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:

{"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.

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

{
  "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:

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

Returns, for anything larger or binary:

{
  "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

{
  "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, like `grep -n`, no matter how many occurrences that line holds.
• `truncated: true` means the scan hit its budget and the results are partial. Narrow the `prefix` or tighten the pattern.
• Line numbers are display-only. Never paste one into `edit`'s `old_str`.

`history`

List the versions of one file, newest first.

Arguments

workspace?   string
path         string
limit        integer   1..1000, default 50
cursor?      string    digits only

Returns

{
  "versions": [
    {
      "version": 7,
      "op": "write",
      "size": 1284,
      "content_hash": "...",
      "created_at": "2026-08-05T09:12:44Z",
      "by_label": "research-agent",
      "by_actor": "agent",
      "moved_from": "drafts/todo.md",
      "purged": false,
      "restorable_until": "2027-08-05T09:12:44Z"
    }
  ],
  "next_cursor": "182734"
}

`op` is one of `write`, `edit`, `move`, `delete`, `restore`. `moved_from`, `by_actor` and `restorable_until` are optional.

Errors: `NOT_FOUND`, `INVALID_PATH`.

Notes

• Newest first, so `limit: 1` is the cheapest way to confirm a write landed.
• `next_cursor` is an opaque string, never a number. It is absent on the last page, which is how you know to stop.
• `purged: true` means retention released the content of that version. The row stays for the audit trail, but `restore` to it returns `NOT_FOUND` with `reason: "version_purged"`.

`activity`

List what changed in a workspace and which agent changed it.

Arguments

workspace?    string
since?        string    RFC 3339 timestamp
path_prefix?  string
limit         integer   1..1000, default 100
cursor?       string

Returns

{
  "events": [
    {
      "at": "2026-08-05T09:12:44Z",
      "actor": "agent",
      "by_label": "research-agent",
      "by_actor": "agent",
      "op": "write",
      "path": "notes/todo.md",
      "old_path": "drafts/todo.md",
      "version": 7
    }
  ],
  "next_cursor": "9014522"
}

`actor` is one of `agent`, `user`, `system`. Newest first.

`op` is `write`, `edit`, `move`, `delete`, `restore`, `purge`, `lock`, `unlock` or `grep`. System sweeps also record `purge_retention` and `purge_workspace_delete`, both with no path. Only `write`, `edit`, `move`, `delete` and a single-file `restore` carry a `version`; on the rest it is null. Note that `purge` carries a real path or folder prefix, so it matches a `path_prefix` filter: if you are auditing a folder from this feed, a purge shows up alongside the writes.

Errors: `INVALID_PATH`.

Notes

• `next_cursor` is an opaque string, never a number. It is absent on the last page, which is how you know to stop.
• This is a poll. There are no webhooks, no triggers and no push. Agents coordinate by calling `activity` on an interval, which fits comfortably inside the rate limit at seconds-to-minutes cadence.
• `since` is a timestamp, not a cursor, and two events can share one. Expect occasional re-delivery and make the work idempotent. See examples/two-agent-handoff.md.

`write`

Create or replace a file with inline content.

Arguments

workspace?         string
path               string
content            string
encoding           "utf8" | "base64"   default "utf8"
mime_type?         string
expected_version?  integer   fail instead of overwriting a concurrent change
override_lock      boolean   default false

Inline cap: 1 MiB decoded. Anything larger goes through `request_upload`.

Returns

{
  "path": "notes/todo.md",
  "version": 8,
  "size": 1301,
  "content_hash": "...",
  "deduplicated": false,
  "unchanged": true
}

`unchanged` is present only when it applies.

Errors: `INVALID_PATH`, `VERSION_CONFLICT`, `LOCKED`, `QUOTA_EXCEEDED`, `TOO_LARGE`.

Notes

• Writing content byte-identical to the current version is a no-op: it returns `unchanged: true` and creates no new version. For a scheduled job that is worth logging loudly, because it usually means the generator did not run.
• Content identical to an older version does create a new version.
• Writing to a tombstoned path resurrects it.

`edit`

Apply string replacements to an existing text file without resending the whole body.

Arguments

workspace?         string
path               string
edits              array of 1..20 objects:
                     old_str      string    min 1 char
                     new_str      string
                     replace_all  boolean   default false
expected_version?  integer
override_lock      boolean   default false

Text files up to 16 MiB.

Returns

{
  "path": "notes/todo.md",
  "version": 9,
  "edits_applied": 2,
  "replacements": [1, 3],
  "size_before": 1301,
  "size_after": 1288,
  "context": "..."
}

`unchanged` is present only when it applies.

Errors: `STRING_NOT_FOUND`, `STRING_NOT_UNIQUE`, `NOT_EDITABLE`, `TOO_LARGE_FOR_EDIT`, `VERSION_CONFLICT`, `LOCKED`, `QUOTA_EXCEEDED`, `NOT_FOUND`.

Notes

• Edits apply in order and commit atomically as one new version, so a 20-edit call is one entry in `history`, not twenty. If any edit fails, none of them land.
• Each `old_str` must match exactly once, otherwise you get `STRING_NOT_FOUND` or `STRING_NOT_UNIQUE`. Set `replace_all` when you mean every occurrence.
• Because edits apply in order, a later `old_str` must match the text as the earlier edits left it.

`move`

Move or rename a file.

Arguments

workspace?         string
from               string
to                 string
expected_version?  integer
overwrite          boolean   default false
override_lock      boolean   default false

Returns

{ "from": "drafts/todo.md", "to": "notes/todo.md", "version": 1 }

`version` is the new version at the destination.

Errors: `NOT_FOUND`, `INVALID_PATH`, `VERSION_CONFLICT` (with `reason: "destination_exists"`), `LOCKED`.

Notes

• The token needs write access to both paths. A prefix rule that covers the source but not the destination fails with `PERMISSION_DENIED`.
• A live destination with `overwrite: false` returns `VERSION_CONFLICT` with `reason: "destination_exists"`. That failure is useful: two workers racing to claim the same item can `move` it, and the loser gets a clean error instead of duplicated work.

`delete`

Tombstone a file.

Arguments

workspace?         string
path               string
expected_version?  integer
override_lock      boolean   default false

Returns

{ "path": "notes/todo.md", "version": 10, "unchanged": true }

`unchanged` is present only when it applies.

Errors: `NOT_FOUND`, `INVALID_PATH`, `VERSION_CONFLICT`, `LOCKED`.

Notes

• This writes a tombstone version, it does not erase content. The file stays recoverable with `restore` for as long as your plan's version history window allows.
• Writing to the same path later resurrects it as a new version on the same history.
• `list` hides tombstoned paths unless you pass `include_deleted: true`.

`restore`

Restore one file to an earlier version, or a whole folder to a point in time.

Arguments, file form:

workspace?      string
path            string
to_version      integer
override_lock   boolean   default false

Arguments, folder form:

workspace?      string
prefix          string
at              string    RFC 3339 timestamp in UTC, e.g. 2026-08-05T14:04:55Z
override_lock   boolean   default false

Returns, file form:

{ "path": "notes/todo.md", "version": 11 }

Returns, folder form:

{
  "restored": 42,
  "deleted": 3,
  "affected_paths": ["content/pricing.md", "content/index.md"],
  "total": 45
}

`affected_paths` is a capped sample; `total` is the true count.

Errors: `NOT_FOUND` (with `reason: "version_purged"` when retention already released the target version), `INVALID_PATH`, `LOCKED`.

Notes

• `at` must be UTC, ending in `Z`, with optional milliseconds. A UTC offset such as `+02:00` is rejected even though it is valid RFC 3339, so convert before you call.
• Restore appends new versions and never rewrites history. The bad versions stay in `history`, so restoring to the wrong timestamp is itself restorable, and restoring twice is safe.
• In the folder form, files that did not exist at `at` receive delete tombstones, counted by `deleted`. They are not erased and a later write brings them back.
• There is no dry run. Size the operation with `list` and confirm a single file with `history` first. Walkthrough: examples/folder-restore-after-bad-run.md.

`lock`

Take an advisory lock on a path.

Arguments

workspace?   string
path         string

Returns

{ "path": "notes/todo.md", "expires_at": "2026-08-05T09:17:44Z" }

Errors: `LOCKED`, `INVALID_PATH`.

Notes

• Advisory and 5 minutes. Call `lock` again with the same token to renew.
• Locks never block reads. A foreign valid lock makes writes return `LOCKED` with `locked_by_label` and `expires_at`, unless the caller passes `override_lock: true`, which is recorded in the activity feed.
• The file need not exist, so you can lock a path you are about to create.
• For work that can be made idempotent, prefer a claim with `move` over a lock: it survives a crash, and a 5-minute TTL does not.

`unlock`

Release a lock this token holds.

Arguments

workspace?   string
path         string

Returns

{ "path": "notes/todo.md", "released": true }

Errors: `PERMISSION_DENIED` (the lock belongs to another token), `INVALID_PATH`.

Notes

• Unlocking a path that holds no lock returns `released: true`, not `NOT_FOUND`. The call says nothing about whether a lock existed, so it is not a way to ask who holds one.

`request_upload`

Start an upload for content too large for inline `write`. First of two steps; see Large file uploads.

Arguments

workspace?         string
path               string
size               integer   positive, the exact byte count of the file
mime_type?         string
expected_version?  integer
override_lock      boolean   default false

Returns

{
  "upload_id": "...",
  "put_url": "https://...",
  "url_expires_at": "2026-08-05T09:27:00Z",
  "max_size": 1073741824
}

Errors: `TOO_LARGE`, `QUOTA_EXCEEDED`, `VERSION_CONFLICT`, `LOCKED`, `INVALID_PATH`.

Notes

• The presigned PUT URL is valid for 15 minutes and the upload record for 1 hour. There is no resumable or multipart upload: if the PUT fails, start again from `request_upload`.
• `size` must be the exact byte count. It is re-checked at `finalize_upload`.

`finalize_upload`

Commit an uploaded file as a new version. Second of two steps.

Arguments

workspace?   string
upload_id    string

Returns

{
  "path": "datasets/corpus.tar.gz",
  "size": 431912448,
  "version": 3,
  "content_hash": "..."
}

Errors: `UPLOAD_EXPIRED`, `VERSION_CONFLICT`, `QUOTA_EXCEEDED`, `TOO_LARGE`.

Notes

• Size and `expected_version` are both re-checked here, so a `VERSION_CONFLICT` can surface at finalize even though `request_upload` succeeded. Someone wrote the path while you were uploading; start again from `request_upload`.
• Calling finalize a second time returns `UPLOAD_EXPIRED`.

Errors

Domain failures come back as a normal tool result carrying `isError: true`, whose text content is JSON:

{ "code": "VERSION_CONFLICT", "message": "...", "current_version": 9 }

They are never protocol-level JSON-RPC errors. Agents and clients should branch on `code`.

Argument validation fails the same way, but the text is not JSON. Passing an argument of the wrong type returns `isError: true` with a plain English string like `MCP error -32602: Input validation error: Invalid arguments for tool activity: ...`, produced by the MCP layer before the request reaches Layven. So parse defensively: an `isError` result whose text will not parse as JSON is a bug in your call, not a Layven domain error. `upload/layven-upload.mjs` does exactly this, falling back to `code: "UNKNOWN"` with the raw text as the message.

`RATE_LIMITED` is the only code worth retrying automatically: sleep `retry_after_ms`, then try again.

Limits

Exceeding a rate limit returns `RATE_LIMITED` with `retry_after_ms`.

Paths and versioning

Paths are UTF-8, `/`-separated and case-sensitive. They are normalized on input:

• no leading slash: `/a/b` becomes `a/b`
• no duplicate slashes
• no `.` or `..` segments, and no empty segments
• no trailing slash on a file
• no control characters
• 1024 bytes maximum

Anything else returns `INVALID_PATH` with a `reason`. Directories are implicit: there are no folder records, and `list` synthesizes folders from path prefixes.

Versioning. Every mutation creates a new version, numbered per file. `delete` writes a tombstone version. `move` creates a version at the destination and tombstones the source. `restore` appends a new version reproducing an earlier state. History is append-only and is never rewritten, which is why a bad restore is itself restorable.

Optimistic concurrency. The default is last-write-wins, which is safe because nothing is lost. When you want a write to fail rather than clobber a concurrent change, pass `expected_version` with the version you read. A mismatch returns `VERSION_CONFLICT` with `current_version` in the payload, so the caller can re-read and decide.

Locks. `lock` takes a 5-minute advisory lock, renewed by calling `lock` again with the same token. A foreign valid lock makes writes return `LOCKED` with `locked_by_label` and `expires_at`; `override_lock: true` proceeds anyway and is recorded in the activity feed. Locks never block reads.

Permissions

Each token is granted access to specific workspaces at one of three levels:

A grant can carry optional prefix rules that restrict a token to particular folders, expressed as `allow` or `deny` lists. Deny beats allow. `move` requires permission on both the source and the destination path.

Give each agent its own token. That is what makes `by_label` in `list`, `history` and `activity` readable, and it is what lets you revoke one agent without touching the others.

Large file uploads

Inline `write` caps at 1 MiB. Above that, upload in three steps.

1. Ask for a URL. Call `request_upload` with the exact byte count:

{ "path": "datasets/corpus.tar.gz", "size": 431912448, "mime_type": "application/gzip" }

{
  "upload_id": "...",
  "put_url": "https://...",
  "url_expires_at": "2026-08-05T09:27:00Z",
  "max_size": 1073741824
}

2. PUT the bytes to `put_url`. This is a plain HTTP PUT of the raw file, not an MCP call. The URL is valid for 15 minutes.

3. Commit it. Call `finalize_upload`:

{ "upload_id": "..." }

{
  "path": "datasets/corpus.tar.gz",
  "size": 431912448,
  "version": 3,
  "content_hash": "..."
}

Why there is no SDK

There is no Layven client library and there will not be one. Layven is a hosted MCP server: you point your client at one URL and your agent gets 14 tools, with no code to write and nothing to keep up to date. This is the one exception. The upload flow has a middle step that is a raw HTTP PUT, and an MCP client cannot issue one, so we ship a single dependency-free script for it. Copy it, read it, change it. It is MIT.

`upload/layven-upload.mjs`

Node 18 or newer. No dependencies, no install.

LAYVEN_TOKEN=agd_your_agent_token \
node upload/layven-upload.mjs ./corpus.tar.gz datasets/corpus.tar.gz \
  [--workspace slug] [--mime type] [--expected-version N] [--override-lock] \
  [--url https://api.layven.io/mcp]

`LAYVEN_TOKEN` is required. `--url` defaults to `https://api.layven.io/mcp`.

Run its tests from the repository root with:

node --test

Examples

• examples/two-agent-handoff.md: agent A drops work on the drive, agent B picks it up by polling `activity`.
• examples/nightly-write-and-verify.md: a cron-driven agent that writes an artifact and proves the write landed.
• examples/folder-restore-after-bad-run.md: triage a bad agent run and roll a folder back to a timestamp.

Plans

Flat price. No meters, no credits.

Data residency

Your files are stored on OVHcloud in Gravelines, France, and are encrypted at rest. No third-party AI or model API ever touches your content. You can export everything as plain files, and deletion is real deletion.

Versioning

The version in `server.json` and in the changelog matches the version the server reports on `initialize`, so you can always check what you are talking to. Documentation changes that do not track a server change do not bump the version.

See CHANGELOG.md.

Support

Bugs in these docs, the examples, or the upload helper: open an issue. Account, billing, or data questions: info@layven.io.

License

MIT covers this repository: the documentation, the examples, and the upload helper. The Layven service itself is closed source.