@jsondb-cloud/mcp

The official MCP (Model Context Protocol) server for jsondb.cloud — a hosted JSON document database. Lets AI agents create, query, and manage documents through natural language.

Install

npm install @jsondb-cloud/mcp

Usage

Once configured, ask your AI assistant:

List all collections in my database

Create a document in "users" with name "Alice" and role "admin"

Find all users where role is "admin"

Show me version history for document abc123 in "orders"

Set up a webhook on "orders" that fires on document.created

Configuration

You need a jsondb.cloud API key. Get one from your dashboard.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jsondb": {
      "command": "npx",
      "args": ["-y", "@jsondb-cloud/mcp"],
      "env": {
        "JSONDB_API_KEY": "jdb_sk_live_..."
      }
    }
  }
}

Claude Code

claude mcp add jsondb \
  -e JSONDB_API_KEY=jdb_sk_live_... \
  -- npx -y @jsondb-cloud/mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "jsondb": {
      "command": "npx",
      "args": ["-y", "@jsondb-cloud/mcp"],
      "env": {
        "JSONDB_API_KEY": "jdb_sk_live_..."
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | | ---------------------- | -------- | -------------------------- | --------------------------------------------------- | | JSONDB_API_KEY | Yes | — | API key (jdb_sk_live_... or jdb_sk_test_...) | | JSONDB_PROJECT | No | v1 | Project namespace | | JSONDB_BASE_URL | No | https://api.jsondb.cloud | API base URL | | JSONDB_MCP_TRANSPORT | No | stdio | Transport type: stdio or http | | JSONDB_MCP_PORT | No | 3100 | HTTP server port (only used with http transport) | | JSONDB_MCP_HOST | No | 127.0.0.1 | HTTP bind address (only used with http transport) |

Tools

Documents

| Tool | Description | | --------------------- | ------------------------------------------------------ | | create_document | Create a new document in a collection | | get_document | Read a single document by ID | | list_documents | List documents with filtering, sorting, and pagination | | update_document | Replace a document entirely | | patch_document | Partially update a document (merge patch) | | delete_document | Delete a document by ID | | count_documents | Count documents matching an optional filter | | json_patch_document | Apply RFC 6902 JSON Patch operations |

Collections

| Tool | Description | | ------------------- | ------------------------------------------------------------------ | | list_collections | List all collections in the current project | | search_documents | Search with advanced filters (eq, gt, contains, in, etc.) | | import_documents | Bulk import with conflict resolution (fail, skip, overwrite) | | export_collection | Export all documents as JSON |

Schemas

| Tool | Description | | ------------------- | ----------------------------------------------- | | get_schema | Get the JSON Schema for a collection | | set_schema | Set a JSON Schema to enforce document structure | | remove_schema | Remove schema validation from a collection | | validate_document | Dry-run validate a document against the schema |

Versions

| Tool | Description | | ----------------- | ------------------------------------------- | | list_versions | List all stored versions of a document | | get_version | Retrieve a specific version snapshot | | restore_version | Restore a document to a previous version | | diff_versions | Compare two versions with a structured diff |

Webhooks

| Tool | Description | | ---------------- | ----------------------------------------------- | | create_webhook | Register a webhook for collection events | | list_webhooks | List all webhooks for a collection | | get_webhook | Get webhook details and recent delivery history | | update_webhook | Update webhook URL, events, or status | | delete_webhook | Delete a webhook | | test_webhook | Send a test event to verify delivery |

Vectors

| Tool | Description | | ---------------------- | --------------------------------------------------------------------------------- | | semantic_search | Search documents using natural language semantic similarity with relevance scores | | store_with_embedding | Store a document and auto-generate a vector embedding for semantic search |

Embeddings are generated asynchronously by the jsondb.cloud backend using Ollama (nomic-embed-text, 768 dimensions). The MCP server delegates to the REST API — no local embedding model or API key is needed.

HTTP Transport

By default the server uses stdio transport (for Claude Desktop, Cursor, etc.). To run as an HTTP server instead, set:

JSONDB_MCP_TRANSPORT=http JSONDB_API_KEY=jdb_sk_live_... npx @jsondb-cloud/mcp

This starts a stateless Streamable HTTP server that creates a fresh McpServer + transport per request (no session affinity required). Endpoints:

| Method | Path | Description | | -------- | --------- | ---------------------------------------- | | POST | /mcp | MCP JSON-RPC requests | | GET | /mcp | SSE stream for server notifications | | DELETE | /mcp | Session termination | | GET | /health | Health check (returns {"status":"ok"}) |

Configure the host and port with JSONDB_MCP_HOST and JSONDB_MCP_PORT (defaults: 127.0.0.1:3100).

Documentation

Full documentation at jsondb.cloud/docs.

Related Packages

| Package | Description | | ------------------------------------------------------------ | ------------------------- | | @jsondb-cloud/client | JavaScript/TypeScript SDK | | @jsondb-cloud/mcp | MCP server for AI agents | | @jsondb-cloud/cli | CLI tool | | jsondb-cloud (PyPI) | Python SDK |

License

MIT