Skip to content

OAuth

Jump to bottom
Chris edited this page Jul 18, 2026 · 93 revisions

Authorization & Identity Management

Tools Resources Prompts
OAuth Code Mode Rate Limiting

Value Proposition Secure your database ecosystem with fine-grained access controls. Our OAuth integration supports a zero-trust architecture, leveraging scope-based permissions to establish clear security boundaries for autonomous AI agents. Read the full value proposition

Configure Authentication

Important

OAuth validation requires the HTTP transport to process bearer tokens. The default stdio transport does not support OAuth.

Streamline your secure deployments and enforce strict access boundaries. Enable enterprise OAuth via standard CLI arguments:

npx -y @neverinfamous/mysql-mcp --mysql mysql://user:password@localhost:3306/database \
          --transport http \
          --port 3000 \
          --server-host 0.0.0.0 \
          --allowed-io-roots "/data,C:/temp" \
          --oauth-enabled \
          --oauth-issuer http://localhost:8081/realms/mysql-mcp \
          --oauth-audience mysql-mcp-client

Or with environment variables:

# OAuth
export OAUTH_ENABLED=true
export OAUTH_ISSUER=http://localhost:8081/realms/mysql-mcp
export OAUTH_AUDIENCE=mysql-mcp-client

# Database
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=user
export MYSQL_PASSWORD=password
export MYSQL_DATABASE=database

npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots "/data,C:/temp"

Note: The --mysql <uri> argument is supported in addition to environment variables.

Note

Global install users can substitute npx -y @neverinfamous/mysql-mcp with mysql-mcp.

Configure Authorization Parameters

Option Environment Description
--oauth-enabled / -o OAUTH_ENABLED Enable OAuth authentication
--oauth-issuer OAUTH_ISSUER Authorization server URL (issuer)
--oauth-audience OAUTH_AUDIENCE Expected token audience
--oauth-jwks-uri OAUTH_JWKS_URI JWKS URI (auto-discovered if not set)
--oauth-clock-tolerance OAUTH_CLOCK_TOLERANCE Clock tolerance in seconds (default: 60)

Client Configuration

Scope Operations Allowed Tool Groups
full All operations All tool groups
read Read-only operations core (read), schema, json, stats, dba-monitor, router
write Data modification core (write), transactions, docstore
admin Administrative operations admin, backup, roles, codemode, shell

Note: The scope mapping table above is illustrative and omits major meta-groups (e.g., vector, spatial, proxysql, etc.). To maintain a strict security boundary, highly privileged operations like Code Mode (mysql_execute_code) and the shell group explicitly require the admin scope.

Pattern Scopes

Fine-grained access with pattern scopes:

Pattern Example Description
db:* db:mydb Access to specific database
table:*:* table:mydb:users Access to specific table

Configure Keycloak Identity Brokering

Verify Prerequisites

Download Keycloak from keycloak.org and extract it.

Note

Windows users should use .bat scripts (e.g., kc.bat, kcadm.bat) instead of .sh and set or $env: instead of export for environment variable configuration.

1. Start Keycloak

cd keycloak-<version>/bin
./kc.sh start-dev --http-port 8081

Wait for: Keycloak started in X.XXs. Listening on: http://0.0.0.0:8081

2. Create Admin Account

  1. Open http://localhost:8081
  2. Create an admin user on first access

3. Create Realm and Client (CLI)

Open a new terminal and navigate to the keycloak-<version>/bin directory.

# Login to admin CLI
./kcadm.sh config credentials --server http://localhost:8081 --realm master --user admin --password YOUR_PASSWORD

# Create mysql-mcp realm
./kcadm.sh create realms -s realm=mysql-mcp -s enabled=true

# Create client with client_credentials grant
./kcadm.sh create clients -r mysql-mcp -s clientId=mysql-mcp-client -s enabled=true -s clientAuthenticatorType=client-secret -s secret=test-secret -s serviceAccountsEnabled=true

# Create scopes
./kcadm.sh create client-scopes -r mysql-mcp -s name=read -s protocol=openid-connect
./kcadm.sh create client-scopes -r mysql-mcp -s name=write -s protocol=openid-connect
./kcadm.sh create client-scopes -r mysql-mcp -s name=admin -s protocol=openid-connect
./kcadm.sh create client-scopes -r mysql-mcp -s name=full -s protocol=openid-connect

4. Verify Token Endpoint

curl -X POST http://localhost:8081/realms/mysql-mcp/protocol/openid-connect/token \
  -d "client_id=mysql-mcp-client" \
  -d "client_secret=test-secret" \
  -d "grant_type=client_credentials"

5. Issuer URL

Your issuer URL is: http://localhost:8081/realms/mysql-mcp

Compliance

mysql-mcp implements:

  • RFC 8414 - OAuth 2.0 Authorization Server Metadata Discovery
  • RFC 7591 - OAuth 2.0 Dynamic Client Registration

Explore Related Topics

MySQL MCP Documentation

Value Proposition Enforce strict execution boundaries and maximize LLM context efficiency for secure, autonomous database interactions. Read the full value proposition

🏠 Home

Launch Your Setup

Connect Ecosystem Tools

Security & Compliance

Scale Your Operations

Explore External Links

Clone this wiki locally