End-to-end encrypted .md documents for agents & humans to collaborate. This is a multiplayer alternative to gog and Google Docs that lets people (via CLI) and agents create, search and sync encrypted markdown docs. This service leverages https://ddocs.new which can be enabled locally or via your preferred cloud set-up to make docs accessible across any device or chatbot interface in complete privacy.

---
name: encrypted docs
description: End-to-end encrypted .md documents for agents & humans to collaborate. This is a multiplayer alternative to gog and Google Docs that lets people (via CLI) and agents create, search and sync encrypted markdown docs. This service leverages https://ddocs.new which can be enabled locally or via your preferred cloud set-up to make docs accessible across any device or chatbot interface in complete privacy.
---

# Fileverse API - Encrypted .md Docs for Agents & Humans

> End-to-end encrypted .md documents for agents & humans to collaborate. This is a multiplayer alternative to gog and Google Docs that lets people (via CLI) and agents create, search and sync encrypted markdown docs. This service leverages [https://ddocs.new](https://ddocs.new) which can be enabled locally or via your preferred cloud set-up to make docs accessible across any device or chatbot interface in complete privacy.

Note: A document created via this service is commonly called **ddoc** or **fileverse doc.** Each document has a unique randomly generated `ddocId`.

## Agents - Setup (Device)

There are different ways to connect to the Fileverse API. First, you need to get the `<SERVER_URL>` from the user.

### MCP

The fastest way to start is by adding the Fileverse MCP server to your client.

#### Claude Code

```bash
claude mcp add --transport http fileverse-api <SERVER_URL>
```

#### Cursor

Add this to your `~/.cursor/config/mcp.json`:

```json
{
  "mcpServers": {
    "fileverse-api": {
      "type": "streamable-http",
      "url": "<SERVER_URL>"
    }
  }
}
```

#### Windsurf

Add this to your MCP config:

```json
{
  "mcpServers": {
    "fileverse-api": {
      "type": "streamable-http",
      "url": "<SERVER_URL>"
    }
  }
}
```

Note: if for some reason MCP is not supported you can fallback to API and check the documentation on the guide.md for exact API Docs.

* * *

## Agents - Setup (Browser)

### MCP

#### ChatGPT

ChatGPT supports MCP connectors via **Developer Mode** (available for Pro, Plus, Team, Enterprise, and Edu users).

**Setup steps:**

1. Open ChatGPT > Settings > Apps > Advanced > toggle Developer Mode on
2. Go to Settings > Apps > click Create
3. Fill in:
    
    * Name: API Encrypted Docs
    * Server URL: `https://<your-server-url>/` (e.g. `https://abc123.ngrok.app/mcp`)
4. Check **"I trust this provider"**
5. Click **Create**

**Using in a chat:**

1. Start a new chat
2. Ask it to create a .md file and store it on Fileverse

#### Claude (Web)

1. Open Claude > Settings > Connector > Add Custom Connector
2. Fill in:
    
    * Name: API Encrypted Docs
    * Server URL: `https://<your-server-url>/` (e.g. `https://abc123.ngrok.app/`)
3. Click **Add**

* * *

## MCP Tools Reference

The Fileverse MCP server exposes **8 tools**. All tools return JSON responses.

### fileverse\_list\_documents

List documents stored in Fileverse. Returns an array of documents with their metadata and sync status.

**Parameters:**

| Name  | Type   | Required | Description                                         |
| ----- | ------ | -------- | --------------------------------------------------- |
| limit | number | No       | Maximum number of documents to return (default: 10) |
| skip  | number | No       | Number of documents to skip (for pagination)        |

**Returns:**

```json
{
  "ddocs": [{ "ddocId": "...", "title": "...", "content": "...", "syncStatus": "synced", "link": "..." }],
  "total": 42,
  "hasNext": true
}
```

**Usage notes:**

* Use `skip` and `limit` to paginate through large document sets
* Check `hasNext` to determine if more documents are available
* Documents are returned with full metadata including `syncStatus` and `link`

* * *

### fileverse\_get\_document

Get a single document by its `ddocId`. Returns the full document including content, sync status, and content hash.

**Parameters:**

| Name   | Type   | Required | Description                    |
| ------ | ------ | -------- | ------------------------------ |
| ddocId | string | Yes      | The unique document identifier |

**Returns:**

```json
{
  "ddocId": "abc123",
  "title": "My Document",
  "content": "# Hello World\n\nThis is my document.",
  "syncStatus": "synced",
  "link": "https://ddocs.new/d/abc123#encryptionKey",
  "localVersion": 3,
  "onchainVersion": 3,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-02T00:00:00.000Z"
}
```

**Usage notes:**

* The `link` field is only available when `syncStatus` is `"synced"`
* The link contains an encryption key fragment after `#` for end-to-end encryption

* * *

### fileverse\_create\_document

Create a new document and wait for syncing. Returns the document with its sync status and public link once synced.

**Parameters:**

| Name    | Type   | Required | Description                               |
| ------- | ------ | -------- | ----------------------------------------- |
| title   | string | Yes      | Document title                            |
| content | string | Yes      | Document content (plain text or markdown) |

**Returns:**

```json
{
  "ddocId": "newDoc123",
  "title": "My New Document",
  "content": "...",
  "syncStatus": "synced",
  "link": "https://ddocs.new/d/newDoc123#encryptionKey"
}
```

**Usage notes:**

* This tool **blocks** until the document is synced to decentralized storage networks (up to 60 seconds)
* Content supports full markdown syntax
* The returned `link` is a shareable, encrypted URL to view the document on ddocs.new
* If sync takes too long, the tool returns with `syncStatus: "pending"` - use `fileverse_get_sync_status` to poll later

* * *

### fileverse\_update\_document

Update an existing document's title and/or content, then wait for the syncing with decentralized storage networks.

**Parameters:**

| Name    | Type   | Required | Description                    |
| ------- | ------ | -------- | ------------------------------ |
| ddocId  | string | Yes      | The unique document identifier |
| title   | string | No       | New document title             |
| content | string | No       | New document content           |

At least one of `title` or `content` must be provided.

**Returns:** Updated document object with sync status and link.

**Usage notes:**

* This tool **blocks** until the update is synced to the decentralized storage networks (up to 60 seconds)
* Only provided fields are updated; omitted fields remain unchanged
* Each update increments the `localVersion`

* * *

### fileverse\_delete\_document

Delete a document by its `ddocId`.

**Parameters:**

| Name   | Type   | Required | Description                              |
| ------ | ------ | -------- | ---------------------------------------- |
| ddocId | string | Yes      | The unique document identifier to delete |

**Returns:**

```json
{
  "message": "Document deleted successfully",
  "data": { "ddocId": "abc123", "..." }
}
```

**Usage notes:**

* Deletion is permanent
* The document's decentralized storage networks’ (including a public blockchain for content hash registry) record will also be updated

* * *

### fileverse\_search\_documents

Search documents by text query. Returns matching documents ranked by relevance.

**Parameters:**

| Name  | Type   | Required | Description                             |
| ----- | ------ | -------- | --------------------------------------- |
| query | string | Yes      | Search query string                     |
| limit | number | No       | Maximum number of results (default: 10) |
| skip  | number | No       | Number of results to skip               |

**Returns:**

```json
{
  "nodes": [{ "ddocId": "...", "title": "...", "content": "...", "syncStatus": "..." }],
  "total": 5,
  "hasNext": false
}
```

**Usage notes:**

* Searches across document titles and content
* Results are ranked by relevance
* Use `skip` and `limit` for pagination

* * *

### fileverse\_get\_sync\_status

Check the sync status of a document. Returns the current syncS