GoSQLX MCP Server Guide#

Table of Contents#

1. Overview
2. Installation
3. Quick Start
4. Starting the Server
5. Configuration
6. Authentication
7. Tools Reference
   • validate_sql
   • format_sql
   • parse_sql
   • extract_metadata
   • security_scan
   • lint_sql
   • analyze_sql
8. AI Assistant Integration
9. Embedding as a Go Library
10. Troubleshooting

Overview#

The GoSQLX MCP server (gosqlx-mcp) exposes all GoSQLX SQL capabilities as Model Context Protocol tools over streamable HTTP. This lets AI assistants like Claude and Cursor call SQL validation, formatting, parsing, linting, and security scanning directly during a conversation.

Key Features#

• 7 SQL Tools: validate, format, parse, extract metadata, security scan, lint, and composite analyze
• Streamable HTTP: Compatible with any MCP client that supports the streamable HTTP transport
• Optional Bearer Auth: Protect the server with a token when exposing to a network
• Multi-Dialect Validation: generic, postgresql, mysql, mariadb, sqlserver, oracle, sqlite, snowflake, bigquery, redshift, clickhouse
• Concurrent Analysis: analyze_sql fans out all 6 tools via sync.WaitGroup - one round trip for a full SQL health report
• Zero Business Logic Duplication: Every tool delegates to the existing pkg/gosqlx, pkg/linter, and pkg/sql/security packages

Remote Server (Public)#

A public GoSQLX MCP server is available at https://mcp.gosqlx.dev/mcp - no installation, no API key, no signup required.

Claude Code#

claude mcp add --transport http gosqlx https://mcp.gosqlx.dev/mcp

Claude Desktop#

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gosqlx": {
      "url": "https://mcp.gosqlx.dev/mcp"
    }
  }
}

Cursor#

Add remote MCP server URL: https://mcp.gosqlx.dev/mcp

Available Tools#

All 7 GoSQLX SQL tools are available instantly:

• validate_sql - Check SQL syntax validity
• format_sql - Format SQL with configurable options
• parse_sql - Parse SQL into AST statement types
• extract_metadata - Extract tables, columns, and functions
• security_scan - Detect SQL injection patterns
• lint_sql - Lint against the ten style rules L001–L010 (not the L011–L030 safety, performance and naming rules)
• analyze_sql - Run all 6 tools in one concurrent request

Rate Limits#

The public server has smart rate limiting to ensure fair usage. These limits come from the rate-limit middleware that the gosqlx-mcp binary installs (NewRateLimitMiddleware); a server embedded with pkg/mcp through Server.Start or Server.Handler has none of them unless you add the middleware yourself (see Embedding as a Go Library):

• Burst: 10 requests/second per IP
• Sustained: 120 weighted-requests/minute per IP
• Heavier tools (analyze_sql) consume more budget than simple ones (validate_sql)
• Limits tighten automatically under high server load
• Streams: at most 4 concurrent GET /mcp (SSE) streams per IP; each opened stream costs 1 unit of sustained budget. A GET refused because 4 streams are already open costs nothing
• Malformed bodies: a non-empty POST body that is not a JSON-RPC message or a non-empty batch costs 1 unit, so malformed requests are not free
• Request body: at most 64 KB, and it must arrive within 30 seconds

A denied request gets HTTP 429 Too Many Requests with a Retry-After header (seconds) and a JSON-RPC error (code -32000) carrying the request's id. A denied initialize, alone or inside a JSON-RPC batch, is the exception: it returns HTTP 200 with the same JSON-RPC error, because mcp-go clients treat any 4xx on initialize as a legacy-SSE server. A GET refused by the stream cap gets HTTP 429 with Retry-After: 60. Every response to a request the limiter evaluates carries X-RateLimit-Limit, X-RateLimit-Remaining (sustained budget left in the current minute) and X-RateLimit-Reset (Unix time the minute ends); stream-cap, body-size and body-timeout rejections, which happen before that check, do not. An oversized body gets HTTP 413 with a JSON-RPC error that names the limit; a body that stalls gets HTTP 408.

The 64 KB limit is deliberate: analyze_sql allocates roughly 500× the SQL size (about 33 MB for 64 KB of SQL, 530 MB for 1 MB), so larger bodies would let a handful of requests exhaust a small instance.

Health Check#

curl https://mcp.gosqlx.dev/health

Self-Hosting#

To run your own instance, use Docker:

docker build -t gosqlx-mcp .
docker run -p 8080:8080 -e GOSQLX_MCP_HOST=0.0.0.0 gosqlx-mcp

Or deploy to Render:

# Connect repo on render.com, it auto-deploys
# Or use render.yaml blueprint

Installation#

Install via go install (Recommended)#

go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx-mcp@latest

The binary is placed in $GOPATH/bin. Make sure that directory is in your PATH.

Build from Source#

git clone https://github.com/ajitpratap0/GoSQLX.git
cd GoSQLX
go build -o gosqlx-mcp ./cmd/gosqlx-mcp

Run without Installing#

go run github.com/ajitpratap0/GoSQLX/cmd/gosqlx-mcp@latest

Quick Start#

Start the Server#

gosqlx-mcp
# gosqlx-mcp: listening on 127.0.0.1:8080 (auth=false)

Smoke Test with curl#

# Validate SQL
curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"validate_sql","arguments":{"sql":"SELECT 1"}}}'

Expected response:

{"valid": true}

MCP Inspector#

npx @modelcontextprotocol/inspector http://127.0.0.1:8080/mcp

This opens an interactive browser UI to browse and call all 7 tools.

Starting the Server#

Environment Variable Examples#

# Local development (all defaults)
gosqlx-mcp

# Custom port
GOSQLX_MCP_PORT=9090 gosqlx-mcp

# Expose to network with bearer auth
GOSQLX_MCP_HOST=0.0.0.0 GOSQLX_MCP_PORT=8080 GOSQLX_MCP_AUTH_TOKEN=my-secret gosqlx-mcp

Task Commands#

If you have Task installed:

task mcp           # Run the MCP server
task mcp:build     # Build the gosqlx-mcp binary
task mcp:test      # Run MCP package tests
task mcp:install   # Install gosqlx-mcp to GOPATH/bin

Graceful Shutdown#

The server listens for context cancellation. When the process receives SIGINT or SIGTERM, it calls http.Server.Shutdown and drains in-flight requests before exiting.

Configuration#

The gosqlx-mcp server is configured exclusively via environment variables. No YAML file is read. All variables are optional - safe defaults are applied for local development.

Notes:

• GOSQLX_MCP_PORT fails fast at startup with a descriptive error if the value is not a valid port number.
• GOSQLX_MCP_AUTH_TOKEN enables bearer token auth for all requests when set to a non-empty string.
• MCP server configuration is independent of .gosqlx.yml - the YAML config is not read by gosqlx-mcp.

Client IP and reverse proxies#

Rate limits are tracked per client IP (IPv6 clients per /64). By default the server uses the TCP peer address (RemoteAddr) and ignores X-Forwarded-For, X-Real-IP and similar headers, because any client can send them: trusting the left-most X-Forwarded-For entry would let a client pick a fresh rate-limit bucket on every request.

Behind a reverse proxy every request comes from the proxy, so all users would share one bucket. Opt in to a forwarded address:

• GOSQLX_MCP_TRUSTED_PROXY_HEADER=CF-Connecting-IP: use a single-IP header that your proxy overwrites on every request. Cloudflare sets CF-Connecting-IP to the visitor address. The hosted server runs on Render, whose edge is Cloudflare, and render.yaml sets this.
• GOSQLX_MCP_TRUSTED_PROXY_HOPS=N: use the entry N positions from the right of X-Forwarded-For (the address appended by the outermost of N trusted proxies). Entries further left are client-supplied and are ignored.

If the header is set, it takes precedence. A missing or unparseable value falls back to RemoteAddr. Only enable either option when every request reaches the server through that proxy; otherwise clients can set the header directly.

Startup warning. When neither option is set, gosqlx-mcp logs one warning at startup: behind a reverse proxy or load balancer every client then shares the proxy's address, so all of them share one rate-limit bucket and one 4-stream GET cap. The warning is expected for a server that clients reach directly; behind a proxy, set one of the options above.

Requiring a proxy secret (optional)#

A trusted client-IP header is only as trustworthy as the path to the server. If the origin can also be reached without the proxy (for example through Render's *.onrender.com hostname rather than the Cloudflare zone), a client can send its own CF-Connecting-IP and pick its rate-limit key. To close that gap, have the proxy add a secret header and tell the server to trust forwarded addresses only on requests that carry it:

GOSQLX_MCP_TRUSTED_PROXY_HEADER=CF-Connecting-IP
GOSQLX_MCP_TRUSTED_PROXY_SECRET_HEADER=X-Origin-Secret
GOSQLX_MCP_TRUSTED_PROXY_SECRET=<random value, at least 16 characters>

With both secret variables set, GOSQLX_MCP_TRUSTED_PROXY_HEADER and GOSQLX_MCP_TRUSTED_PROXY_HOPS apply only when the last value of the secret header equals the secret (compared in constant time). Requests with a missing or wrong secret are not rejected; they are keyed by RemoteAddr, so traffic that bypasses the proxy shares one bucket instead of choosing its own. The secret header is removed before the request reaches the MCP handler, and the secret never appears in logs or configuration errors. With neither variable set, behaviour is unchanged.

To set the header with a Cloudflare Transform Rule:

1. Generate a secret, for example openssl rand -hex 32.
2. In the Cloudflare dashboard for the zone that serves the MCP hostname, open Rules → Transform Rules → Modify Request Header and create a rule.
3. Match the MCP hostname, for example Hostname equals mcp.example.com.
4. Add the action Set static, header name X-Origin-Secret, value the secret. Set overwrites any value a client sent, so clients cannot supply their own.
5. Deploy the rule, then set GOSQLX_MCP_TRUSTED_PROXY_SECRET_HEADER and GOSQLX_MCP_TRUSTED_PROXY_SECRET on the server as secret environment variables (on Render, in the dashboard rather than in render.yaml) and restart it.

Deploy the rule before the server variables: until both sides agree, requests fall back to the shared RemoteAddr bucket rather than failing. Rotate the secret the same way. The rule must cover every hostname that should get per-client limits.

HTTP server limits#

gosqlx-mcp sets ReadHeaderTimeout 10 s, IdleTimeout 120 s and MaxHeaderBytes 32 KB. It sets no global ReadTimeout/WriteTimeout, because those would cut long-lived GET /mcp SSE streams. POST bodies instead get a 30 s read deadline in the rate-limit middleware, so slow-body (slowloris) connections are closed with HTTP 408.

Authentication#

By default the server accepts all requests without authentication. To enable bearer token auth, set GOSQLX_MCP_AUTH_TOKEN:

GOSQLX_MCP_AUTH_TOKEN=supersecret gosqlx-mcp
# gosqlx-mcp: listening on 127.0.0.1:8080 (auth=true)

All requests must then include the Authorization header:

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer supersecret" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"validate_sql","arguments":{"sql":"SELECT 1"}}}'

Requests missing or carrying an incorrect token receive HTTP 401 Unauthorized. The Bearer scheme is matched case-insensitively and surrounding whitespace is ignored. Tokens are compared in constant time (SHA-256 digests with crypto/subtle). The BearerAuthMiddleware wraps the streamable HTTP handler and is a no-op when auth is disabled.

Tools Reference#

All tools accept a required sql string parameter. Errors are reported at three levels:

• Result data: validate_sql reports invalid SQL as a normal result with valid: false; analyze_sql reports sub-tool failures under its errors key.
• Tool errors (isError: true, message in the text content): input problems the model can fix, such as a missing, empty or non-string sql, SQL that parse_sql, extract_metadata or format_sql cannot parse, or an optional argument of the wrong type or out of range (the message names the argument).
• JSON-RPC errors: unknown tools, malformed requests and genuine server faults.

Optional arguments must match their schema type. Absent or null means the default. For clients that stringify scalars, "true"/"false" and decimal-integer strings are also accepted.

validate_sql#

Description: Validate SQL syntax. Optionally specify a dialect.

Parameters#

Response#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"validate_sql","arguments":{"sql":"SELECT id FROM users","dialect":"postgresql"}}}'

{
  "valid": true,
  "dialect": "postgresql"
}

Invalid SQL:

{
  "valid": false,
  "error": "unexpected token 'FORM' at position 7"
}

format_sql#

Description: Format SQL with configurable indentation and keyword casing.

Parameters#

Response#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"format_sql","arguments":{"sql":"select id,name from users where active=true","uppercase_keywords":true,"indent_size":4}}}'

{
  "formatted_sql": "SELECT\n    id,\n    name\nFROM users\nWHERE active = true",
  "options": {
    "indent_size": 4,
    "uppercase_keywords": true,
    "add_semicolon": false
  }
}

parse_sql#

Description: Parse SQL and return an AST summary: statement count and types, optionally for a specific dialect.

Parameters#

Response#

SQL Server GO batch separators (*ast.BatchSeparator) are left out of statement_count and statement_types. parse_sql defaults to the generic dialect. Set "dialect": "sqlserver" to parse T-SQL scripts containing GO; repeat counts on GO do not increase statement_count.

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"parse_sql","arguments":{"sql":"SELECT 1; INSERT INTO t VALUES (1)"}}}'

{
  "statement_count": 2,
  "statement_types": [
    "*ast.SelectStatement",
    "*ast.InsertStatement"
  ]
}

extract_metadata#

Description: Extract tables, columns, and functions referenced in SQL.

Parameters#

Response#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"extract_metadata","arguments":{"sql":"SELECT u.id, COUNT(o.id) FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.id"}}}'

{
  "tables": ["users", "orders"],
  "columns": ["id", "id"],
  "functions": ["COUNT"]
}

Since v1.17.0 (issue #849), an unqualified name in ORDER BY or HAVING that matches a SELECT-list alias is treated as the alias, so extract_metadata and the metadata part of analyze_sql no longer report SELECT aliases as columns. For SELECT count(*) AS orders FROM t GROUP BY customer_id ORDER BY orders, columns holds only customer_id.

security_scan#

Description: Scan SQL for injection patterns: tautologies, UNION attacks, stacked queries, comment bypasses, and more.

Parameters#

Response#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"security_scan","arguments":{"sql":"SELECT * FROM users WHERE id = 1 OR 1=1"}}}'

{
  "is_clean": false,
  "has_critical": true,
  "has_high": true,
  "total_count": 1,
  "critical_count": 1,
  "high_count": 0,
  "medium_count": 0,
  "low_count": 0,
  "findings": [
    {
      "severity": "CRITICAL",
      "pattern": "tautology",
      "description": "Tautology injection detected: always-true condition",
      "risk": "Authentication bypass or full table disclosure",
      "suggestion": "Use parameterized queries; never interpolate user input into SQL"
    }
  ]
}

lint_sql#

Description: Lint SQL against the ten GoSQLX style rules L001–L010, the same set gosqlx lint runs, with L005's maximum line length fixed at 100 characters. The safety, performance and naming rules L011–L030, which gosqlx.Lint also runs, are not applied.

Parameters#

Response#

Lint Rules#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lint_sql","arguments":{"sql":"select id,name from users"}}}'

{
  "violation_count": 1,
  "violations": [
    {
      "rule": "L007",
      "rule_name": "KeywordCase",
      "severity": "warning",
      "message": "Keyword 'select' should be uppercase",
      "line": 1,
      "column": 1,
      "suggestion": "Use 'SELECT' instead of 'select'"
    }
  ]
}

analyze_sql#

Description: Run all 6 analysis tools concurrently and return a composite report. Results are keyed by tool name (validate, parse, metadata, security, lint, format). Partial failures appear under an errors key.

Parameters#

Response#

Example#

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"analyze_sql","arguments":{"sql":"SELECT id FROM users"}}}'

{
  "validate": {
    "valid": true
  },
  "parse": {
    "statement_count": 1,
    "statement_types": ["*ast.SelectStatement"]
  },
  "metadata": {
    "tables": ["users"],
    "columns": ["id"],
    "functions": []
  },
  "security": {
    "is_clean": true,
    "has_critical": false,
    "has_high": false,
    "total_count": 0,
    "critical_count": 0,
    "high_count": 0,
    "medium_count": 0,
    "low_count": 0,
    "findings": []
  },
  "lint": {
    "violation_count": 0,
    "violations": []
  },
  "format": {
    "formatted_sql": "SELECT id\nFROM users",
    "options": {
      "indent_size": 2,
      "uppercase_keywords": false,
      "add_semicolon": false
    }
  }
}

AI Assistant Integration#

Claude Code plugin#

The repository doubles as a Claude Code plugin marketplace. The gosqlx plugin connects to the hosted server and adds SQL skills, /gosqlx:analyze, /gosqlx:format, /gosqlx:lint and /gosqlx:security commands, a read-only sql-reviewer agent and an optional hook that validates edited .sql files:

/plugin marketplace add ajitpratap0/GoSQLX
/plugin install gosqlx@gosqlx

See plugins/gosqlx/README.md for local mode and privacy notes.

ChatGPT#

gosqlx-mcp is also a ChatGPT app (OpenAI Apps SDK): analyze_sql renders an interactive report widget, and every tool returns structuredContent. Add https://mcp.gosqlx.dev/mcp as a connector in ChatGPT developer mode (no auth). See integrations/chatgpt/README.md and CHATGPT_APP.md.

Claude Desktop#

Add gosqlx-mcp to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gosqlx": {
      "command": "gosqlx-mcp",
      "args": ["--stdio"]
    }
  }
}

After restarting Claude Desktop, the 7 GoSQLX tools appear in the tool panel. Claude can now validate, lint, and analyze SQL on your behalf in any conversation.

Cursor#

Add the MCP server to your Cursor configuration (.cursor/mcp.json in your project root, or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "gosqlx": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Start gosqlx-mcp before opening Cursor (or add it to a startup script). Cursor will connect to the running server and expose the tools in its Agent mode.

With Authentication#

When running with GOSQLX_MCP_AUTH_TOKEN:

{
  "mcpServers": {
    "gosqlx": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Embedding as a Go Library#

Import pkg/mcp directly to embed the MCP server in your own application:

import "github.com/ajitpratap0/GoSQLX/pkg/mcp"

func main() {
    cfg, err := mcp.LoadConfig()
    if err != nil {
        log.Fatal(err)
    }
    srv := mcp.New(cfg)
    if err := srv.Start(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Start and Handler apply bearer auth only. They do not apply the rate limiting described under Rate Limits: there is no per-client rate limit, no GET stream cap, no request body size cap and no body read deadline. That is fine on 127.0.0.1, but before exposing an embedded server to untrusted clients, serve Handler wrapped in NewRateLimitMiddleware, as gosqlx-mcp does:

cfg, err := mcp.LoadConfig()
if err != nil {
    log.Fatal(err)
}
srv := mcp.New(cfg)
defer srv.Shutdown(context.Background())

httpSrv := &http.Server{
    Addr:              cfg.Addr(),
    Handler:           mcp.NewRateLimitMiddleware(cfg, srv.Handler()),
    ReadHeaderTimeout: 10 * time.Second,
}
log.Fatal(httpSrv.ListenAndServe())

NewRateLimitMiddleware honours the trusted-proxy settings in cfg (see Client IP and reverse proxies). Shutdown stops the idle-session sweeper that Handler starts; it does not close an http.Server you built yourself.

Public API#

Config Struct#

type Config struct {
    Host      string // GOSQLX_MCP_HOST (default "127.0.0.1")
    Port      int    // GOSQLX_MCP_PORT (default 8080, range 1–65535)
    AuthToken string // GOSQLX_MCP_AUTH_TOKEN (default "" = auth disabled)

    OpenAIAppsChallenge string // GOSQLX_MCP_OPENAI_APPS_CHALLENGE (default "" = not served)
    TrustedProxyHeader  string // GOSQLX_MCP_TRUSTED_PROXY_HEADER (default "" = not used)
    TrustedProxyHops    int    // GOSQLX_MCP_TRUSTED_PROXY_HOPS (default 0 = X-Forwarded-For ignored)

    // Optional: trust the two fields above only when this header carries the secret.
    TrustedProxySecretHeader string // GOSQLX_MCP_TRUSTED_PROXY_SECRET_HEADER (default "" = not required)
    TrustedProxySecret       string // GOSQLX_MCP_TRUSTED_PROXY_SECRET
}

Custom Context with Cancellation#

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Cancel on SIGINT
go func() {
    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt)
    <-c
    cancel()
}()

cfg := mcp.DefaultConfig()
srv := mcp.New(cfg)
log.Fatal(srv.Start(ctx))

Troubleshooting#

Server Won't Start - "address already in use"#

Another process is using port 8080. Change the port:

GOSQLX_MCP_PORT=9090 gosqlx-mcp

Or find and stop the conflicting process:

lsof -i :8080

Server Won't Start - "GOSQLX_MCP_PORT: expected integer"#

The port value is not a valid integer:

# Wrong
GOSQLX_MCP_PORT=abc gosqlx-mcp

# Correct
GOSQLX_MCP_PORT=8080 gosqlx-mcp

HTTP 401 on All Requests#

Authentication is enabled but the token is missing or wrong. Check GOSQLX_MCP_AUTH_TOKEN and include the header:

curl ... -H "Authorization: Bearer your-token"

"command not found: gosqlx-mcp"#

$GOPATH/bin is not in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

MCP Inspector Can't Connect#

Verify the server is running and listening on the correct address:

curl -s http://127.0.0.1:8080/mcp
# Should return an MCP protocol response, not "connection refused"

analyze_sql Returns Partial Results with "errors" Key#

One or more sub-tools failed. The errors map identifies which tools failed and why. Successful results are always returned alongside errors.

{
  "validate": {"valid": false, "error": "syntax error"},
  "errors": {
    "parse": "parse failed: unexpected token at position 0",
    "metadata": "parse failed: unexpected token at position 0"
  }
}

The format, security scan, and lint tools operate on the raw SQL string independently and may still succeed.

Resources#

• Repository: https://github.com/ajitpratap0/GoSQLX
• Issues: https://github.com/ajitpratap0/GoSQLX/issues
• MCP Specification: https://modelcontextprotocol.io/specification
• mark3labs/mcp-go: https://github.com/mark3labs/mcp-go