PowerSync DevTools Agent Tools

PowerSync DevTools gives coding agents, such as Claude Code or Codex, tools to query your app’s local database, read its sync status, and run sync actions, such as reconnect or clear the local data. The tools are the same on each platform, but the way an agent connects to them depends on your platform.

These tools work with your running app. To let an agent search the PowerSync documentation, use the docs MCP server instead.

Connect a Coding Agent

Platform	How an agent connects
Vite, Nuxt DevTools 4, Capacitor, and Node.js	The MCP endpoint.
React Native	The Rozenite agent CLI.
Dart and Flutter	The MCP server built in to the Dart SDK, which has its own tools. Read this resource.

Nuxt DevTools 3 does not have an MCP endpoint. To use the agent tools in a Nuxt app, use Nuxt DevTools 4.

Tools

These tools are available on the MCP endpoint and in React Native. The MCP endpoint and the Rozenite agent CLI pass the inputs in different ways.

Tool	Inputs	Returns
`query`	`sql`, and `params` (optional)	`{ columns, rows }`. Each row is an array in column order.
`schema`	None	The schema, as the PowerSync SQLite core receives it.
`info`	None	The endpoint, the token, the client ID, the connection method, and the core version.
`status`	None	The last sync status that the client reported.
`upload-queue`	None	The number and size of the local changes that wait to upload.
`action`	`action`, and `args` (optional)	Runs one of these actions: `reconnect`, `disconnect`, `clearData`, `requestCheckpoint`, `subscribeStream`, `unsubscribeStream`.

For subscribeStream and unsubscribeStream, args is { name, params?, ttl?, priority? }.

query can change data. A write to one of your schema tables goes into the upload queue, and your connector uploads it like a write from your app. action with clearData deletes the local data, including the local changes in the upload queue, and downloads the data again. info returns the current JWT. Give these tools only to agents that you trust.

MCP Endpoint

Vite, Nuxt DevTools 4, Capacitor, and Node.js serve the tools as MCP (Model Context Protocol) tools.

Host	Endpoint
Vite and Capacitor	`http://localhost:5173/__devtools/__mcp` (use your dev server port)
Nuxt DevTools 4	`http://localhost:3000/__devtools/__mcp` (use your dev server port)
Node.js	`<url>/__mcp`, where `url` is the value that `enablePowerSyncDiagnostics()` returns

On the web, the tools get the database from an open app tab. Keep your app open in a browser that Vite DevTools trusts, or the tools return an error. For a Capacitor app, keep the app running with live reload on a trusted simulator or emulator. For a Node.js app, set a fixed port in enablePowerSyncDiagnostics() so that the endpoint stays the same when your app restarts.

Add the Endpoint to Your Agent

The endpoint accepts only requests that have a loopback Origin header, such as http://localhost:5173. Some MCP clients do not send this header, so add it to the client configuration. For example, to add the Vite endpoint to Claude Code:

claude mcp add --transport http powersync-devtools http://localhost:5173/__devtools/__mcp --header "Origin: http://localhost:5173"

If your MCP client cannot send the header, set allowedOrigins: false. Read Origin and Authorization.

Coding agents such as Claude Code can add the server themselves. Start your dev server, open your app, and give the agent a prompt like this one:

Connect to the PowerSync DevTools MCP server of my running app.
The endpoint is http://localhost:5173/__devtools/__mcp. It uses the Streamable HTTP transport.
Every request must send the header "Origin: http://localhost:5173".
Add the server, then call powersync_sources and powersync_status and tell me the sync state.

Change the URL and the port to match your host. Some agents must restart before they can use a new MCP server.

Pass Tool Arguments

On the MCP endpoint, each tool name has the powersync_ prefix, such as powersync_query. The endpoint also has a powersync_sources tool, which returns the attached databases with their ID and SDK. The tools take positional arguments named arg0 and arg1. The last argument of most tools is the database ID. Pass null to use the first attached database, or call powersync_sources to list the IDs.

Tool	Arguments
`powersync_sources`	None
`powersync_query`	`arg0`: `{ sql, params? }` `arg1`: database ID or `null`
`powersync_schema`, `powersync_info`, `powersync_status`, `powersync_upload-queue`	`arg0`: database ID or `null`
`powersync_action`	`arg0`: `{ action, args? }` `arg1`: database ID or `null`

Origin and Authorization

To change how the endpoint checks requests, use the mcp setting:

Value	Result
`'auto'`	The default. The endpoint accepts requests with a loopback `Origin` header.
`{ allowedOrigins: false }`	The endpoint also accepts requests without an `Origin` header. Use this only when the server listens on `localhost`.
`{ authorization: '<token>' }`	Requests must also send `Authorization: Bearer <token>`. Read the token from an environment variable.
`false`	Turns off the endpoint.

Set it in your host:

devtools option (Vite 8.3+)
DevTools() plugin (Vite 7+)
Nuxt DevTools 4
Node.js

export default defineConfig({
  devtools: { apply: 'serve', mcp: { allowedOrigins: false } },
  plugins: [powersyncDevtools()]
});

export default defineConfig({
  plugins: [...(await DevTools({ mcp: { allowedOrigins: false } })), powersyncDevtools()]
});

export default defineNuxtConfig({
  vite: {
    devtools: { mcp: { allowedOrigins: false } }
  }
});

const devtools = await enablePowerSyncDiagnostics(db, { mcp: { allowedOrigins: false } });

Test the Endpoint

Use curl to check that the endpoint works. This example counts the operations in the local oplog:

curl -X POST http://localhost:5173/__devtools/__mcp \
  -H 'Origin: http://localhost:5173' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"powersync_query","arguments":{"arg0":{"sql":"SELECT count(*) AS operations FROM ps_oplog"},"arg1":null}}}'

If the response is 403 Forbidden, the request has no loopback Origin header.

React Native

In React Native apps, the usePowerSyncDevTools() hook registers the tools for the Rozenite agent CLI. The tools are in the powersync/diagnostics domain, for example npx rozenite agent powersync/diagnostics status. To use the tools, set up PowerSync DevTools for React Native, and keep the app running with Metro started with WITH_ROZENITE=true. The agent runs the commands from your app’s folder.

Give your coding agent a prompt like this one:

My React Native app runs PowerSync DevTools as a Rozenite plugin, and Metro runs with WITH_ROZENITE=true.
Inspect the app's PowerSync client with the Rozenite agent CLI. Run all commands from the app folder.
1. Run `npx rozenite skills show core` and `npx rozenite skills show cli` to learn how the CLI works.
2. Run `npx rozenite agent powersync/diagnostics` to list the PowerSync tools. Add `--help` after a tool name to see its arguments.
3. Call the `status` and `upload-queue` tools, and tell me the sync state.
4. When you finish, run `npx rozenite agent session stop`.

The agent session holds the app’s only debugger connection. Step 4 releases it.

The CLI passes the inputs as named flags, such as --sql. The tools have no database ID and there is no sources tool, because the tools use the database that you pass to the hook.

Get Started

Configuration Details

Sync Streams

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

PowerSync DevTools Agent Tools

Connect a Coding Agent

Tools

MCP Endpoint

Add the Endpoint to Your Agent

Pass Tool Arguments

Origin and Authorization

Test the Endpoint

React Native

​Connect a Coding Agent

​Tools

​MCP Endpoint

​Add the Endpoint to Your Agent

​Pass Tool Arguments

​Origin and Authorization

​Test the Endpoint

​React Native

Connect a Coding Agent

Tools

MCP Endpoint

Add the Endpoint to Your Agent

Pass Tool Arguments

Origin and Authorization

Test the Endpoint

React Native