SapientDB MCP Server

The official MCP (Model Context Protocol) server for SapientDB — block-native document storage for AI agents.

This package allows AI agents like Claude to read, write, search, and manage documents stored in SapientDB.

Quick Start

1. Get your API token

Sign up at sapientdb.com and create a Personal Access Token (PAT) or Service Account key.

2. Add to Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sapientdb": {
      "command": "npx",
      "args": ["@agentopolis/sapientdb-mcp"],
      "env": {
        "SAPIENTDB_TOKEN": "your_token_here"
      }
    }
  }
}

3. Restart Claude Desktop

After updating the config, restart Claude Desktop to load the MCP server.

4. Start using it

Ask Claude things like:

• "List my documents in SapientDB"
• "Create a new document called 'Meeting Notes'"
• "Add a paragraph about our Q1 goals"
• "Search for anything mentioning authentication"
• "Update the introduction block"

Installation Options

Option A: npx (Recommended)

No installation required. Claude runs the package directly:

{
  "command": "npx",
  "args": ["@agentopolis/sapientdb-mcp"]
}

Option B: Global Install

npm install -g @agentopolis/sapientdb-mcp

Then configure Claude:

{
  "command": "sapientdb-mcp"
}

Option C: Local Install

npm install @agentopolis/sapientdb-mcp

Then configure Claude:

{
  "command": "node",
  "args": ["./node_modules/@agentopolis/sapientdb-mcp/dist/index.js"]
}

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SAPIENTDB_TOKEN | Yes | — | Your PAT or Service Account key | | SAPIENTDB_URL | No | https://sapientdb.com | API endpoint |

Self-Hosted Deployments

For self-hosted SapientDB instances, specify your custom URL:

{
  "mcpServers": {
    "sapientdb": {
      "command": "npx",
      "args": ["@agentopolis/sapientdb-mcp"],
      "env": {
        "SAPIENTDB_TOKEN": "your_token_here",
        "SAPIENTDB_URL": "https://sapientdb.yourcompany.com"
      }
    }
  }
}

Available Tools

Document Management

| Tool | Description | |------|-------------| | list_documents | List all documents the agent can access | | get_document | Get a document's metadata and details | | create_document | Create a new document | | update_document | Update document title or metadata | | delete_document | Delete a document and all its blocks |

Block Management

| Tool | Description | |------|-------------| | list_blocks | List blocks in a document (ordered) | | get_block | Get a specific block's content | | create_block | Create a new markdown block | | batch_create_blocks | Create multiple blocks in one operation (up to 100) | | update_block | Update a block's content or metadata | | delete_block | Delete a block |

Search

| Tool | Description | |------|-------------| | search_blocks | Full-text search across all accessible blocks. Supports filtering by tags, block_type, source, metadata, and date range. | | search_documents | Search documents by title. Supports filtering by metadata fields. |

Permissions

| Tool | Description | |------|-------------| | get_permissions | View permissions for a document or block | | set_permissions | Set permissions (requires admin scope) |

Tool Examples

Creating a Document

User: "Create a document called 'Project Roadmap' in my default collection"

Claude will call:
  create_document(title: "Project Roadmap", collection_id: "...")

Adding Content

User: "Add a section about Q1 milestones"

Claude will call:
  create_block(
    document_id: "...",
    content_markdown: "## Q1 Milestones\n\n...",
    block_type: "heading"
  )

Batch Adding Content (Conversations/Logs)

User: "Save this conversation to my notes"

Claude will call:
  batch_create_blocks(
    document_id: "...",
    blocks: [
      { content_markdown: "User: How do I...", block_type: "user", metadata: { turn: 1 } },
      { content_markdown: "Assistant: You can...", block_type: "assistant", metadata: { turn: 2 } },
      { content_markdown: "User: Thanks!", block_type: "user", metadata: { turn: 3 } }
    ]
  )

This is ideal for:

• Ingesting multi-turn conversations
• Batch importing log entries
• Saving agent execution traces

Searching

User: "Find everything about authentication"

Claude will call:
  search_blocks(query: "authentication")

Filtering by Metadata

Documents and blocks support custom metadata fields that can be used for filtering:

User: "Find all published API documentation"

Claude will call:
  search_blocks(
    query: "API",
    filters: { metadata: { status: "published", category: "api" } }
  )

User: "Show me draft documents"

Claude will call:
  search_documents(
    query: "...",
    metadata: { status: "draft" }
  )

Using Metadata Patch

Update metadata fields without overwriting existing ones:

User: "Mark this document as reviewed by Alice"

Claude will call:
  update_document(
    document_id: "...",
    metadata_patch: { status: "reviewed", reviewer: "alice" }
  )

This merges with existing metadata rather than replacing it entirely.

Time-Based Filtering

Filter blocks by creation or modification time (useful for agent logs):

User: "Show me conversation messages from the last hour"

Claude will call:
  list_blocks(
    document_id: "...",
    created_after: "2026-01-19T11:00:00Z"
  )

User: "Find error logs from today"

Claude will call:
  search_blocks(
    query: "error",
    scope: { type: "global" },
    filters: {
      created_after: "2026-01-19T00:00:00Z",
      metadata: { level: "ERROR" }
    }
  )

Time filters accept ISO 8601 format and include created_after, created_before, updated_after, and updated_before.

Updating Content

User: "Update the introduction to mention our new product"

Claude will call:
  update_block(
    block_id: "...",
    content_markdown: "Updated introduction text..."
  )

Token Types

Personal Access Tokens (PATs)

Best for individual use with Claude or other personal agents.

• Created in Account Settings
• Inherits your collection memberships
• Scopes: read, write, admin

Format: pat_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Service Account Keys

Best for shared automation and integrations.

• Created in Collection Settings (admin only)
• Scoped to a single collection
• Scopes: read, write, admin

Format: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token Scopes

| Scope | Capabilities | |-------|-------------| | read | List and read documents and blocks | | write | Create, update, and delete documents and blocks | | admin | Manage permissions, collection settings |

Most agents need read and write scopes. Only grant admin if the agent needs to manage permissions.

Error Handling

The MCP server returns clear error messages:

| Error | Cause | Solution | |-------|-------|----------| | SAPIENTDB_TOKEN is required | Missing token | Set the environment variable | | Unauthorized | Invalid or expired token | Create a new token | | Forbidden | Insufficient permissions | Check token scopes | | Not found | Resource doesn't exist | Verify the ID | | Rate limited | Too many requests | Wait and retry |

Debugging

Check if the server starts

SAPIENTDB_TOKEN=your_token npx @agentopolis/sapientdb-mcp

You should see initialization output. If not, check:

• Token is valid
• Network connectivity to SAPIENTDB_URL

View logs

Claude Desktop logs MCP server output. Check:

macOS: ~/Library/Logs/Claude/ Windows: %APPDATA%\Claude\logs\

Test the API directly

curl -H "Authorization: Bearer your_token" \
  https://sapientdb.com/api/documents

Development

Building from Source

git clone https://github.com/agentopolis/sapientdb.git
cd sapientdb/mcp
npm install
npm run build

Running Locally

# Set your token
export SAPIENTDB_TOKEN=your_token

# Run in development mode
npm run dev

# Or run the built version
npm start

Testing with Claude

Point Claude at your local build:

{
  "mcpServers": {
    "sapientdb-dev": {
      "command": "node",
      "args": ["/path/to/sapientdb/mcp/dist/index.js"],
      "env": {
        "SAPIENTDB_TOKEN": "your_token"
      }
    }
  }
}

Running Tests

The MCP server includes comprehensive integration tests that verify all tools and authentication flows work correctly.

Quick Start (Auth Tests - No Setup Required)

Auth tests are fully self-contained and create their own accounts/tokens:

# Run auth tests only (no PAT needed)
SAPIENTDB_URL=http://localhost:3000 npm test -- tests/auth.test.ts

Full Test Suite (Requires PAT)

For the complete test suite, you need a PAT with read/write access:

# Install dependencies
npm install

# Run all tests
SAPIENTDB_URL=http://localhost:3000 SAPIENTDB_TOKEN=your_pat npm test

# Run tests in watch mode
SAPIENTDB_URL=http://localhost:3000 SAPIENTDB_TOKEN=your_pat npm run test:watch

# Run specific test file
SAPIENTDB_URL=http://localhost:3000 SAPIENTDB_TOKEN=your_pat npm test -- tests/documents.test.ts

Creating a Test PAT

You can create a PAT for testing via the API:

# 1. Register a test user
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "TestPassword123!"}'

# 2. Create a PAT (use access_token from step 1)
curl -X POST http://localhost:3000/api/pats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"name": "Test PAT", "scope": "read_write"}'

Test Coverage:

| Test File | Description | Tests | Requires Token | |-----------|-------------|-------|----------------| | client.test.ts | API client unit tests (timeout, errors) | 30 | No (mocked) | | auth.test.ts | Auth flows, PAT scopes, service accounts | 34 | No (self-contained) | | documents.test.ts | Document CRUD operations | 15 | Yes | | blocks.test.ts | Block CRUD operations | 18 | Yes | | batch-blocks.test.ts | Batch block creation for conversations | 15 | Yes | | search.test.ts | Search functionality | 11 | Yes | | time-filters.test.ts | Time-based filtering for logs | 15 | Yes | | metadata.test.ts | Metadata CRUD and search filtering | 15 | Yes | | permissions.test.ts | Permission get/set | 21 | Yes (admin for set) | | validation.test.ts | Schema validation edge cases | 66 | Yes | | concurrency.test.ts | Race conditions, optimistic locking | 20 | Yes | | errors.test.ts | Error handling edge cases | 30 | Yes |

Environment Variables:

| Variable | Required | Description | |----------|----------|-------------| | SAPIENTDB_URL | Yes | API endpoint (e.g., http://localhost:3000) | | SAPIENTDB_TOKEN | For most tests | PAT with read/write access | | SAPIENTDB_TEST_COLLECTION_ID | No | Specific collection for tests |

Running tests without a PAT:

# Run unit tests (no server needed)
npm test -- tests/client.test.ts

# Run auth tests (no PAT needed, but needs running server)
SAPIENTDB_URL=http://localhost:3000 npm test -- tests/auth.test.ts

Notes:

• client.test.ts uses mocked fetch - runs without any server
• auth.test.ts is fully self-contained and creates its own users, PATs, and service accounts
• Permission set_permissions tests require a PAT with read_write_admin scope
• Tests run sequentially to avoid race conditions

Changelog

v0.1.10

• Added Organizations support (Heroku/GitHub-style model)
• Personal organizations are automatically created for each user
• Team organizations support owner, admin, and member roles
• Collections now require an organization context
• Updated test setup to use organization-scoped collection creation

v0.1.9

• Added batch_create_blocks tool for efficient multi-block ingestion (up to 100 blocks per call)
• Ideal for conversation logs, agent traces, and bulk content import
• Added composite index on (document_id, created_at) for faster time-filtered queries

v0.1.8

• Added time-based filtering (created_after, created_before, updated_after, updated_before) to search_blocks and list_blocks
• Essential for agent log and conversation history queries
• Added blocks_created_at_idx index for efficient time-range queries

v0.1.7

• Added metadata filtering for search_blocks and search_documents
• Added metadata_patch for partial metadata updates on documents and blocks
• New MetadataEditor component in the UI for managing custom metadata fields

v0.1.6

• Added service account support
• Improved error messages
• Fixed token validation

v0.1.5

• Initial public release
• Document and block management
• Full-text search
• Permission management

Links

• SapientDB Homepage
• Full Documentation
• Web Application
• GitHub Repository
• npm Package

License

MIT