# JsonDBCloud Mcp

> MCP server for jsondb.cloud — connect AI agents to your JSON database

- **Type:** MCP server
- **Install:** `agentstack add mcp-jsondbcloud-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JsonDBCloud](https://agentstack.voostack.com/s/jsondbcloud)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JsonDBCloud](https://github.com/JsonDBCloud)
- **Source:** https://github.com/JsonDBCloud/mcp

## Install

```sh
agentstack add mcp-jsondbcloud-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @jsondb-cloud/mcp

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

[](https://www.npmjs.com/package/@jsondb-cloud/mcp)
[](https://www.npmjs.com/package/@jsondb-cloud/mcp)
[](https://github.com/JsonDBCloud/mcp/actions)
[](https://www.typescriptlang.org/)
[](https://nodejs.org)
[](https://bundlephobia.com/package/@jsondb-cloud/mcp)
[](https://github.com/JsonDBCloud/mcp)
[](https://github.com/JsonDBCloud/mcp)
[](https://opensource.org/licenses/MIT)

## Install

```bash
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](https://jsondb.cloud).

### Claude Desktop

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

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

### Claude Code

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

### Cursor

Add to `.cursor/mcp.json`:

```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:

```bash
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](https://jsondb.cloud/docs).

## Related Packages

| Package                                                      | Description               |
| ------------------------------------------------------------ | ------------------------- |
| [@jsondb-cloud/client](https://www.npmjs.com/package/@jsondb-cloud/client) | JavaScript/TypeScript SDK |
| [@jsondb-cloud/mcp](https://www.npmjs.com/package/@jsondb-cloud/mcp) | MCP server for AI agents |
| [@jsondb-cloud/cli](https://www.npmjs.com/package/@jsondb-cloud/cli) | CLI tool |
| [jsondb-cloud](https://pypi.org/project/jsondb-cloud/) (PyPI) | Python SDK |

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JsonDBCloud](https://github.com/JsonDBCloud)
- **Source:** [JsonDBCloud/mcp](https://github.com/JsonDBCloud/mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jsondbcloud-mcp
- Seller: https://agentstack.voostack.com/s/jsondbcloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.