MCP / AI Agent Support

Connect AI agents (Claude, ChatGPT, custom agents) to jsondb.cloud via the Model Context Protocol.

The MCP server lets AI assistants discover and use your jsondb.cloud database through a standardized tool interface. Compatible with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compliant AI agent.

Installation

npx @jsondb-cloud/mcp

Setup

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

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

Environment Variables

Variable	Required	Default	Description
JSONDB_API_KEY	Yes	—	Your jsondb.cloud API key (`jdb_sk_live_...` or `jdb_sk_test_...`)
JSONDB_PROJECT	No	`v1`	Project namespace to use
JSONDB_BASE_URL	No	`https://api.jsondb.cloud`	Custom API URL (for self-hosted)

Available Tools

The MCP server exposes 28 tools across 6 categories. AI agents discover these automatically.

Documents

create_documentCreate a new document in a collection

get_documentRead a single document by ID

list_documentsList documents with filtering, sorting, and pagination

update_documentReplace a document entirely

patch_documentPartially update specific fields (merge patch)

json_patch_documentApply RFC 6902 JSON Patch operations

delete_documentDelete a document by ID

count_documentsCount documents matching a filter

Collections

list_collectionsList all collections in the project

search_documentsAdvanced search with operators (eq, gt, contains, in, etc.)

import_documentsBulk import with conflict resolution (fail, skip, overwrite)

export_collectionExport all documents as JSON

Schemas

get_schemaGet the JSON Schema for a collection

set_schemaEnforce document structure with JSON Schema

remove_schemaRemove validation from a collection

validate_documentDry-run validate a document without saving

Versions

list_versionsList all stored versions of a document

get_versionRetrieve a specific version snapshot

restore_versionRestore a document to a previous version

diff_versionsCompare two versions side by side (Pro)

Webhooks

create_webhookRegister a webhook for collection events

list_webhooksList all webhooks on a collection

get_webhookGet webhook details and delivery history

update_webhookUpdate URL, events, or status

delete_webhookRemove a webhook

test_webhookSend a test event to verify delivery

Vectors

semantic_searchSearch documents using natural language similarity (powered by pgvector)

store_with_embeddingStore a document and auto-generate a vector embedding for semantic search

Examples

Once configured, talk to your database in plain English. Here are some real conversations:

Build a quick prototype

You:"I need a todo app backend. Create a 'todos' collection with a schema that requires title (string) and done (boolean), then add 3 sample todos."

AI:Done! I set up a schema on 'todos' requiring title and done, then created: "Buy groceries" (not done), "Review PR #42" (done), and "Deploy v2" (not done). Your collection is ready — want me to set up a webhook so you get notified on changes?

Explore and query data

You:"What collections do I have? Show me a summary of each."

AI:You have 3 collections: 'users' (47 docs), 'orders' (312 docs), and 'products' (89 docs). The users collection has a schema enforcing email and name fields. Want me to dig into any of them?

You:"Find all orders over $100 from the last week, sorted by amount descending."

AI:Found 23 orders over $100 in the last 7 days. The top 3: order #ord_x9k ($450, 2 items), order #ord_m3j ($380, 5 items), and order #ord_p7q ($299, 1 item). Want the full list?

Manage data with version history

You:"Someone changed the pricing on product prod_abc. Show me the version history and roll it back to yesterday's version."

AI:Product prod_abc has 4 versions. Version 3 (yesterday) had price: $29.99, version 4 (today) changed it to $9.99. I've restored it to version 3 — price is back to $29.99.

Bulk operations and import

You:"Import these 50 customer records into the 'customers' collection. Skip any that already exist."

AI:Imported 50 records with onConflict=skip. 47 created successfully, 3 skipped (already existed). The 'customers' collection now has 142 documents total.

Set up webhooks

You:"Set up a webhook on the 'orders' collection that posts to my Slack endpoint whenever an order is created or updated."

AI:Webhook created! It will fire on document.created and document.updated events, posting to your Slack URL. I sent a test event — want me to verify it arrived?

Semantic search with AI memory

You:"Remember that my favorite programming language is Rust and I prefer functional patterns"

AI:Stored! I've saved that to your knowledge base with a semantic embedding — I'll recall it whenever it's relevant.

You:"What do you know about my coding preferences?"

AI:Based on your knowledge base: you prefer Rust as your main language and favor functional programming patterns. Want me to remember anything else?

The MCP server works with any MCP-compatible AI tool. Try it with Claude Code for managing data from your terminal, or Claude Desktop for a conversational database experience.