jazz-tools-mcp-v2

MVP Model Context Protocol data connector for the official jazz-tools@alpha server.

This project deliberately targets the current Jazz 2 alpha architecture. It does not use the old jazz-nodejs / CoJSON 0.9.x APIs and it does not start a second Jazz sync server.

Jazz itself also ships jazz-tools mcp. That is the official documentation MCP (list_pages, search_docs, get_doc). This repository is a separate, privileged connector for application data.

Security boundary

This MCP connects with Jazz admin/backend credentials and therefore operates with privileged backend access, not an end-user permission-scoped session.

• read tools may see rows an ordinary user would not be permitted to read
• mutation tools, when enabled, may bypass ordinary row-level user policies
• JAZZ_MCP_PRINCIPAL changes write attribution only; it does not impersonate a user for permission evaluation

Treat this process and its secrets like database administrator credentials. Run it only in trusted operator/agent environments. Writes remain disabled by default.

What it connects to

The official self-hosted server is started like this:

export JAZZ_APP_ID="replace-with-your-app-id"
export JAZZ_ADMIN_SECRET="replace-with-admin-secret"

npx jazz-tools@alpha server "$JAZZ_APP_ID" \
  --port 1625 \
  --data-dir ./data \
  --admin-secret "$JAZZ_ADMIN_SECRET"

The MCP connector talks to that process in two ways:

1. HTTP catalogue endpoints discover the published Jazz schema.
2. Jazz's own NAPI backend runtime connects to the app-scoped WebSocket sync endpoint for queries and mutations.

There is no SQL bridge and no invented REST CRUD API.

MVP tools

Read tools:

• jazz_status
• jazz_reload_schema
• jazz_list_tables
• jazz_describe_table
• jazz_query
• jazz_get_row

Mutation tools, disabled by default:

• jazz_insert
• jazz_update
• jazz_delete

jazz_query uses the same generic Jazz query JSON shape used by the official Jazz Inspector. Example:

{
  "table": "todos",
  "where": {
    "done": false,
    "title": { "contains": "ship" }
  },
  "select": ["title", "done", "$createdBy", "$updatedAt"],
  "orderBy": [{ "column": "title", "direction": "asc" }],
  "limit": 25
}

Where predicates are AND-combined. Query-level OR is not part of the current Jazz query API. The connector validates operators against the Jazz column type (contains for text, range operators for numeric/timestamp fields, etc.).

Query-time Jazz magic columns supported by the connector are:

• $canRead, $canEdit, $canDelete
• $createdBy, $createdAt, $updatedBy, $updatedAt

They are query-only system columns and cannot be passed as mutation fields. Row id is likewise not accepted in mutation values; Jazz manages row identity separately.

Requirements

• Node.js 22.12+
• a running jazz-tools@alpha server
• an app ID
• the server admin secret
• at least one published schema for the app

For Node backends Jazz requires jazz-napi as an explicit dependency. This repository therefore depends on both:

jazz-tools@alpha
jazz-napi@alpha

The connector follows the npm alpha tag for both packages. The research snapshot for this MVP was checked against official Jazz 2.0.0-alpha.53 and repository commit fa7d33b3ecfc9fcb673cd7c7bb9c35d700255e1d on 2026-08-16.

Setup

npm install
cp .env.example .env

Set at least:

JAZZ_SERVER_URL=http://127.0.0.1:1625
JAZZ_APP_ID=replace-with-your-app-id
JAZZ_ADMIN_SECRET=replace-with-admin-secret

Then:

npm run build
npm start

The server uses MCP stdio. Do not write logs to stdout; stdout is reserved for MCP JSON-RPC.

Example MCP client config

{
  "mcpServers": {
    "jazz-data": {
      "command": "node",
      "args": ["/absolute/path/to/jazz-tools-mcp-v2/dist/index.js"],
      "env": {
        "JAZZ_SERVER_URL": "http://127.0.0.1:1625",
        "JAZZ_APP_ID": "your-app-id",
        "JAZZ_ADMIN_SECRET": "your-admin-secret"
      }
    }
  }
}

Using a name such as jazz-data avoids confusion with Jazz's built-in docs MCP.

Schema discovery

The MCP does not crawl your source tree for schema.ts.

At first use it calls the official Jazz schema catalogue APIs:

GET /apps/<app-id>/schemas
GET /apps/<app-id>/schema/<schema-hash>
X-Jazz-Admin-Secret: ...

By default it selects the newest published schema using publishedAt, falling back to the last returned hash. Pin a specific schema with:

JAZZ_SCHEMA_HASH=<hash>

If the server has no schema yet, run your Jazz application in its normal development flow so structural schema auto-sync occurs, or use the project's normal jazz-tools@alpha deploy workflow.

After a new deployment, call jazz_reload_schema or restart the MCP process. Jazz contexts are schema-bound after initialization, so reload tears down the old local runtime before loading the new schema.

Authentication modes

Preferred production backend mode

The Jazz v2 backend documentation recommends explicit backend identity for server-connected server-owned work. Start Jazz with both secrets:

npx jazz-tools@alpha server "$JAZZ_APP_ID" \
  --port 1625 \
  --data-dir ./data \
  --admin-secret "$JAZZ_ADMIN_SECRET" \
  --backend-secret "$JAZZ_BACKEND_SECRET"

Then configure:

JAZZ_BACKEND_SECRET=...

The MCP uses context.asBackend(schema).

To stamp mutation provenance while retaining backend-level permissions:

JAZZ_MCP_PRINCIPAL=mcp:agent

This uses context.withAttribution(...) and requires JAZZ_BACKEND_SECRET.

Compatibility mode: admin secret only

The exact self-host example above contains only --admin-secret. The current alpha Rust server accepts admin_secret in its WebSocket handshake as backend access, so the connector retains an admin-only compatibility path and uses the context's admin-authenticated transport.

This path is tested in CI against Jazz's official startLocalJazzServer + deploy test utilities. For production server-owned work, prefer the explicit backend-secret mode above.

Write safety

Writes are off by default:

JAZZ_MCP_ALLOW_WRITES=false

Enable explicitly:

JAZZ_MCP_ALLOW_WRITES=true

Mutation confirmation defaults to Jazz's edge durability tier:

JAZZ_MCP_DURABILITY=edge

Allowed values are local, edge, and global.

The MVP intentionally does not expose schema mutation, permission mutation, migrations, arbitrary HTTP requests, raw SQLite access, or arbitrary SQL. Those operations have stronger Jazz-specific invariants and should continue through the official validate, deploy, permissions, and migrations flows.

The current query surface also intentionally omits relation include(...), recursive gather(...), reactive subscriptions, and arbitrary query JSON.

Verification

CI runs on Node 22.12 and performs:

npm install
npm run check
npm test
npm run build

Tests include an integration smoke test using the official Jazz testing utilities to:

1. start an in-memory Jazz server
2. deploy a real schema and permissions bundle
3. connect this MCP adapter without passing the backend secret
4. discover the published schema through the admin catalogue
5. insert/query/update/delete through Jazz's native runtime and WebSocket protocol

For a manual server test, see docs/testing.md.

Test with MCP Inspector

After installing dependencies and building:

npx @modelcontextprotocol/inspector node ./dist/index.js

Provide the Jazz environment variables in the shell that launches the Inspector.

Research

• docs/research/official-alpha-server.md
• docs/research/analogs-and-old-server.md
• docs/research/attached-jazz-v2-docs-review.md
• docs/architecture.md

License

MIT