Readyset MCP Server

Readyset ships a built-in Model Context Protocol server. AI assistants like Claude Code, Cursor, and anything else that speaks MCP can introspect your Readyset deployment, analyze proxied queries, and manage caches directly — no custom integration code required.

Two deployment shapes are supported:

Both expose the same set of tools.

Tools

Under the hood each tool issues the corresponding Readyset SQL command, so the semantics match what you would run in a mysql or psql shell. 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 is not desired, set READYSET_TLS_DISABLE_VERIFICATION=true (encryption is still negotiated, only the server's identity is not 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>']

Creates a new token. 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

Lists all stored tokens with their metadata. Does not show the raw value or hash.

SHOW MCP TOKENS;

Columns: name, scope, created_at, expires_at.

ALTER MCP TOKEN

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

Update 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>';

Immediately 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 does not 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 is 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 does not 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 is not verified, so do not use this in production.

Tool call returns "token scope 'read_only' does not permit tool 'drop_cache'"

The token does not 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 "cannot 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.