@zenstackhq/studio-mcp-remote

@zenstackhq/studio-mcp-remote is a local stdio MCP server proxy designed for ZenStack Studio.

Problem

The hosted ZenStack Studio MCP server interacts with a user's database via a ZenStack proxy. When that proxy runs locally (e.g. http://localhost:2311), the hosted remote server cannot directly connect to it. @zenstackhq/studio-mcp-remote bridges this gap: it runs locally as a stdio MCP server (for Claude Desktop, Cursor, etc.), forwarding schema and check tool requests to the remote Studio MCP server while intercepting execute database tool requests locally to call the localhost proxy.

Installation & Usage

You can run @zenstackhq/studio-mcp-remote directly with npx or pnpm dlx:

npx -y @zenstackhq/studio-mcp-remote --remote <studio-mcp-url> --proxy <local-proxy-url> --authorization <authorization-token>

CLI Options

• --remote, -r (Required): The URL of the remote ZenStack Studio MCP server.
• --proxy, -p (Required): The URL of your local database proxy (e.g. http://localhost:2311).
• --authorization, -a (Required): The base64-encoded UserClaim authorization token.

If any required flag is omitted, the CLI prints usage instructions and exits with status code 1.

MCP Client Configuration

Claude Desktop (claude_desktop_config.json)

Add @zenstackhq/studio-mcp-remote to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zenstack": {
      "command": "npx",
      "args": [
        "-y",
        "@zenstackhq/studio-mcp-remote",
        "--remote",
        "https://studio.zenstack.dev/api/mcp/YOUR_PROJECT_REF",
        "--proxy",
        "http://localhost:2311",
        "--authorization",
        "eyJ0eXBlIjoic3VwZXJVc2VyIn0="
      ]
    }
  }
}

Cursor / VS Code MCP Configuration

{
  "mcpServers": {
    "zenstack": {
      "command": "npx",
      "args": [
        "-y",
        "@zenstackhq/studio-mcp-remote",
        "--remote",
        "https://studio.zenstack.dev/api/mcp/YOUR_MCP_REF",
        "--proxy",
        "http://localhost:2311",
        "--authorization",
        "eyJ0eXBlIjoic3VwZXJVc2VyIn0="
      ]
    }
  }
}

Generating the Authorization Token

The --authorization token is a base64-encoded JSON payload matching the UserClaim type:

export type UserClaim = { type: 'superUser' } | { type: 'user'; data: Record<string, unknown> }

SuperUser Claim Example (bash)

echo -n '{"type":"superUser"}' | base64
# Output: eyJ0eXBlIjoic3VwZXJVc2VyIn0=

Regular User Claim Example (bash)

echo -n '{"type":"user","data":{"id":"user-123","role":"ADMIN"}}' | base64
# Output: eyJ0eXBlIjoidXNlciIsImRhdGEiOnsiaWQiOiJ1c2VyLTEyMyIsInJvbGUiOiJBRE1JTiJ9fQ==

Development

# Install dependencies using pnpm
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

License

MIT