MCP servers

The Model Context Protocol (MCP) lets AI assistants and coding agents use tools. JSONPad has two MCP servers:

The docs server lets an agent search and read these docs, look up the exact contract of any API endpoint, SDK method, command or error code, and check the write rules, flows and schema documents it writes for you before you save them. It's free, needs no account or token, and can't see or change your data.
The API server lets an agent build and run a backend on your account, with the access you give it when it connects: create lists, indexes and write rules, read and change items, sync schema documents, undo mistakes from the history, and call your flows. See the API server.

They work best together: the API server does the work, and the docs server explains it and checks rules and flows without spending any of your requests.

Adding the docs server

The docs server is hosted at https://mcp.jsonpad.io/docs (Streamable HTTP). Add it to your agent with that URL. In Claude Desktop and on claude.ai, go to Settings, then Connectors, and add a custom connector with the URL. In other clients:

1claude mcp add --transport http jsonpad-docs https://mcp.jsonpad.io/docs

The hosted server is always up to date: it's deployed with these docs, so it describes exactly what's live.

Running it locally

The same server is also the @basementuniverse/jsonpad-docs-mcp npm package, which runs on your own machine over stdio. It needs Node.js 22.12 or later.

1claude mcp add jsonpad-docs -- npx -y @basementuniverse/jsonpad-docs-mcp

A local copy carries a snapshot of the docs from when it was published. When JSONPad upgrades the engines that run write rules and flows, it adds a warning to its checks until you update it.

What it can do

Reading the docs:

search_docs searches these docs, the SDK references and the command line tool reference. Exact identifiers work well: error names, headers, SDK methods, commands and variables.
read_doc reads a page, or one section of it, as markdown, and list_docs lists the pages.
list_api_endpoints and get_api_endpoint give an endpoint's full contract: parameters, headers, request body, responses, and the SDK method that calls it.
get_sdk_method and get_cli_command give a method's signature and example, or a command's options.
lookup_error explains an error code, and get_plan_limits gives each plan's limits.

Checking your work:

check_write_rules compiles write rules and runs their tests.
eval_write_rule tries one write against some rules, and shows what every rule evaluated to.
check_flow compiles a flow and runs its tests against in-memory data.
validate_sync_document checks a schema sync document, and every rule set and flow in it.
validate_token_permissions checks token permissions, and warns about rules that probably don't do what you meant.

It also has prompts for common jobs (getting started, designing a schema document, writing rules or a flow, explaining an error, planning token permissions, recovering lost data), and resources for every page and JSON schema.

Checking rules and flows

The checkers use the same engines as the API, at the same versions, so rules and flows that pass here behave the same way when you save them. They run on what you send and nothing else: rule lookups and flow reads find the items in the test document, never your data, and checking doesn't count against your request allowance.

You don't need to call them yourself. Ask your agent for what you want, and it can write, check and fix until the tests pass:

12345678

Write rules for my "moves" list so that only a game's players can add a move,
and only on their turn. Add tests, and check them with the JSONPad docs server
until they pass.

Check jsonpad-schema.json and the rules and flow files it references.

Why would this write be refused? Rules: rules/games.rules. The write: an update
by identity "bob" that changes /turn from "alice" to "bob".

A schema document that references files (rulesFile, flowFile and their tests) can only be checked if the agent sends their contents too, which it can do when it has your files open.

The API server

The API server talks to the JSONPad API with one of your API tokens, so it can do exactly what that token can: the token's permissions, your plan's limits and every list's write rules apply to it as they do to your own apps. Every call it makes counts against your request allowance, like any other request.

Adding the API server

The API server is hosted at https://mcp.jsonpad.io/api (Streamable HTTP). Add it with the URL. In Claude Desktop and on claude.ai, go to Settings, then Connectors, and add a custom connector with the URL. In other clients:

1claude mcp add --transport http jsonpad https://mcp.jsonpad.io/api

The first time it connects, your client opens a JSONPad page in your browser (log in first, if you aren't). It shows which app is asking and where it will send you back to, and you choose what it may do:

Read only: view your lists, items and indexes, their history and stats, and export them as a schema document.
Read and write: also create, change, delete and restore items and indexes, and change and delete lists.
Everything: everything an API token can do, including identities and flows. A flow runs with your full privileges, so only choose this for an agent you trust completely.

You can limit Read only and Read and write to some of your lists, and choose when access ends. Allowing creates an API token for the app, which appears in your tokens, tagged oauth. Delete it there to take the app's access away; it will ask you to connect again. Connecting the same app again replaces its token, and the token counts towards your plan's token limit.

Adding the API server with a token

You can also use one of your own API tokens, as a bearer token in the Authorization header. The hosted server passes it to the API with each request, and never stores it.

1claude mcp add --transport http jsonpad https://mcp.jsonpad.io/api --header "Authorization: Bearer <YOUR TOKEN>"

Give the agent a token of its own, with only the permissions it needs: access to the lists it should work on, and sync-schema if it should manage lists and indexes. A token that can only view your lists is a safe way to start. A token that's allowed everything can also create and run flows, which can do anything you can.

Running the API server locally

The API server is also the @basementuniverse/jsonpad-mcp npm package, which runs on your own machine over stdio, with your token in the JSONPAD_API_TOKEN environment variable. It needs Node.js 22.12 or later.

1claude mcp add jsonpad --env "JSONPAD_API_TOKEN=<YOUR TOKEN>" -- npx -y @basementuniverse/jsonpad-mcp

Use the npm package for a token with an IP allowlist: requests from the hosted server come from its address, not yours.

Options

On the hosted server, options go in the URL's query string, e.g. https://mcp.jsonpad.io/api?readOnly=true. For the npm package, they're environment variables.

Read-only (readOnly=true, JSONPAD_READ_ONLY=true) gives the agent only the tools that change nothing.
Toolsets (toolsets=, JSONPAD_TOOLSETS) chooses which groups of tools to offer, separated by commas. The default is lists,items,indexes,history,rules,schema; add flows to call your flows, and identities to manage your app's identities.
Acting as an identity (the x-identity-token and x-identity-group headers, or JSONPAD_IDENTITY_TOKEN and JSONPAD_IDENTITY_GROUP) makes every request as one of your app's identities, which is handy for testing write rules and what each user can see.

What the API server can do

Lists and items: create, read, update and delete them, filter, order and search items, and change part of an item's data with a merge, a JSON Patch or a JSON pointer.
Indexes: create them, wait for them to build, and rebuild a failed one.
Schema sync: export your lists as a schema sync document, show you a plan of what a document would change, and apply it.
Write rules: try a write against a list's rules without making it, and show the writes they refused and why.
History: read an item's events, and restore an item to an earlier version, even after it was deleted.
Flows (with the flows toolset): call your endpoint flows.
Identities (with the identities toolset): list, create, update and delete them.
Your token: what it's allowed to do, your plan's limits, and how many requests you've used this month.

It also has prompts (designing a backend, writing rules for a list, finding out why a write was refused, inspecting a list, undoing changes), and resources for your lists, their schemas and rules, and your items.

Some things to ask an agent that has it:

12345678910

Set up a backend for my recipe app as a schema sync document: recipes with a
title, ingredients and an author, searchable by title. Show me the plan before
you apply it.

Why does my game get 403s when players move? Check the denials on the "moves"
list and tell me which rule refused them.

Mark every task in "tasks" that was due before today as late.

I deleted the wrong item from "orders" this morning. Find it and put it back.

Safeguards

It won't overwrite your app's changes. When it writes something it read, it sends the item's ETag, so the write fails rather than replacing a change made in the meantime.
It won't delete values it can't see. Values hidden by a guard index aren't shown to API tokens, so the server refuses writes that would replace them, and changes those items field by field instead.
Mistakes can be undone. Every item write makes a new version, and deleted items can be restored. Deleting a whole list or an identity can't be undone, so those need the agent to repeat the name back, as does a schema sync that deletes things.
Your agent can ask first. Every tool says whether it only reads, whether it can destroy data, and whether it reaches outside JSONPad (calling a flow), so your agent's app can ask you before the ones that matter.

Limits and privacy

The hosted servers allow about 120 requests a minute between them from each IP address, and the docs server 30 checks. A check can take up to 10 seconds, and its input can be up to 512 KB. The npm package has no limits of its own.

Each API server tool call makes one or more requests to the API, so your plan's rate limits and request allowance apply as usual.

We log which tools are used and what's searched for, so we can tell where the docs fall short. For the API server, we log only which tools are called and whether they worked: never what you send or get back. The logs don't include your IP address, your token, or anything you send to the checkers. See the privacy policy.