Readyset MCP Server

The Readyset Model Context Protocol server lets AI assistants inspect a Readyset deployment and manage its caches.

This server connects to Readyset. For RDST query analysis and audits, use RDST's MCP tools. Neither MCP server exposes RDST's Continuous monitoring Inbox or nightly reports.

Two deployment shapes are supported:

Both expose the same set of tools.

Tools

Each tool issues a Readyset SQL command. See the command reference for details on each command.

Stdio binary: local setup

The readyset-mcp binary spawns as a child process of your MCP client (e.g. Claude Code) and connects to Readyset over the standard SQL wire protocol.

Install

Build from source in the Readyset repo:

cargo build --release -p readyset-mcp
# Binary at target/release/readyset-mcp

Register with Claude Code

claude mcp add readyset -- /path/to/readyset-mcp

Then edit ~/.claude.json and add the connection environment variables to the readyset entry:

{
  "mcpServers": {
    "readyset": {
      "command": "/path/to/readyset-mcp",
      "env": {
        "READYSET_HOST": "127.0.0.1",
        "READYSET_PORT": "3307",
        "READYSET_USER": "root",
        "READYSET_PASSWORD": "",
        "READYSET_DB_TYPE": "mysql"
      }
    }
  }
}

Configuration

TLS

Set READYSET_SSLMODE=require to connect over TLS. The system root store is used by default. To trust a custom CA, point READYSET_TLS_ROOT_CERT at a PEM file. For self-signed setups where verification isn't desired, set READYSET_TLS_DISABLE_VERIFICATION=true (encryption is still negotiated, only the server's identity isn't checked).

{
  "mcpServers": {
    "readyset": {
      "command": "/path/to/readyset-mcp",
      "env": {
        "READYSET_HOST": "readyset.internal",
        "READYSET_PORT": "3307",
        "READYSET_USER": "root",
        "READYSET_PASSWORD": "",
        "READYSET_DB_TYPE": "mysql",
        "READYSET_SSLMODE": "require",
        "READYSET_TLS_ROOT_CERT": "/etc/ssl/readyset-ca.pem"
      }
    }
  }
}

When to use stdio

• Individual developer, single workstation
• Quick local experimentation
• You already have SQL credentials and don't want to manage tokens

Embedded HTTP: shared / remote setup

The readyset binary itself hosts an MCP endpoint on a dedicated port. AI assistants connect over HTTP(S) using Bearer tokens that you create from inside a SQL session.

Enable the endpoint

readyset \
  --enable-mcp \
  --mcp-address 127.0.0.1:6035 \
  ... # your usual flags

Flags:

Create a token

Connect to Readyset with any SQL client and run:

CREATE MCP TOKEN 'claude-desktop' WITH SCOPE cache_admin;

Readyset returns a single row containing the raw token value:

+-------------------------------------------+
| token                                     |
+-------------------------------------------+
| rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc  |
+-------------------------------------------+

This is the only time the raw value is visible. Copy it immediately.

You can also set an expiration when creating the token:

CREATE MCP TOKEN 'claude-desktop'
  WITH SCOPE cache_admin
  EXPIRES '2027-01-01T00:00:00Z';

Register with Claude Code

claude mcp add --transport http readyset https://readyset.example.com:6035/mcp \
  --header "Authorization: Bearer rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc"

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "readyset": {
      "type": "http",
      "url": "http://readyset.example.com:6035/mcp",
      "headers": {
        "Authorization": "Bearer rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc"
      }
    }
  }
}

When to use HTTP

• Multiple users sharing one Readyset
• Remote access (MCP client not on the same host as Readyset)
• You want fine-grained permissions (per-token scopes, expiration)
• Administrative control over who can do what via MCP

Token management

All MCP tokens are managed with SQL. There are no separate admin tools.

CREATE MCP TOKEN

CREATE MCP TOKEN '<name>'
  [WITH SCOPE <scope>]
  [EXPIRES '<rfc3339-datetime>']

CREATE MCP TOKEN creates a new token and returns the raw value once.

• <name>: human-readable identifier, used in later DROP/ALTER statements. Must be unique.
• <scope>: one of read_only, cache_admin, full. Defaults to read_only.
• EXPIRES '<rfc3339>': optional UTC timestamp after which the token becomes invalid. Omit for a non-expiring token.

SHOW MCP TOKENS

SHOW MCP TOKENS lists tokens and metadata. It doesn't show the raw value or hash.

SHOW MCP TOKENS;

Each row shows the token's name and scope. Check created_at and expires_at for its creation and expiration times.

ALTER MCP TOKEN

ALTER MCP TOKEN '<name>' SET EXPIRES '<rfc3339-datetime>'
ALTER MCP TOKEN '<name>' SET NEVER EXPIRES

ALTER MCP TOKEN updates a token's expiration without rotating its value. Useful for extending a soon-to-expire token without having to reconfigure the client.

DROP MCP TOKEN

DROP MCP TOKEN '<name>';

DROP MCP TOKEN revokes the token. The next request using it returns 401.

Scopes

Each token carries one of three scopes. The MCP endpoint enforces the scope on every tool invocation. Requests that violate scope are rejected with HTTP 403.

Choose the narrowest scope that covers the client's needs. Most interactive AI use cases are fine with read_only; only promote to cache_admin when you want the assistant to actually modify cache state.

Security notes

• Token values are hashed: Readyset stores only the SHA-256 hash. If a token is lost, you must DROP MCP TOKEN and CREATE MCP TOKEN to issue a new one.
• Plaintext HTTP: the current MCP endpoint doesn't terminate TLS itself. For any non-local deployment, put it behind a TLS-terminating proxy (nginx, Caddy, Envoy, an ingress controller, etc.).
• Bearer tokens are the only auth: there's no IP allowlist, no OAuth, no mTLS. Treat a token like a password.
• Scope enforcement is centralized: adding a new MCP tool without updating the scope map causes it to default to full, failing closed.

Troubleshooting

"Connection failed" on initial Claude Code registration

The MCP server binary must be able to reach Readyset over its SQL port. For stdio, check the env vars; for HTTP, check the --mcp-address and firewall.

Quick test (HTTP transport):

curl -i -X POST http://readyset.example.com:6035/mcp \
  -H "Authorization: Bearer rs_mcp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A 200 response means the HTTP layer and token auth are working; the problem is in the Claude Code config.

Stdio binary fails to connect with a TLS handshake error

Readyset is presenting a certificate the system root store doesn't trust. Two options:

1. Point READYSET_TLS_ROOT_CERT at the PEM file that issued Readyset's certificate. This is the recommended path for internal CAs.
2. For a quick local check, set READYSET_TLS_DISABLE_VERIFICATION=true. Encryption is still negotiated, but the server's identity isn't verified, so don't use this in production.

Tool call returns "token scope 'read_only' doesn't permit tool 'drop_cache'"

The token doesn't have the required scope. Either create a new token with a broader scope or drop this one and recreate it.

CREATE CACHE over MCP reports "can't parse query"

The create_cache tool passes the SQL text through to Readyset's parser exactly as you provide it. Test the same query against Readyset directly via mysql or psql to confirm whether the issue is the query itself or the tool pipeline.

Token appears in SHOW MCP TOKENS but requests get 401

Check the expires_at column. If the timestamp is in the past, the token is expired. Either ALTER MCP TOKEN to extend it or drop and recreate.