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

  Copy

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