@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