Layven

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