GoSQLX MCP Server Guide

Version: v1.10.0 Last Updated: 2026-03-09

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: postgresql, mysql, sqlite, sqlserver, oracle, snowflake, generic
• 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

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.

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 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. The server returns tool-semantic failures (e.g., invalid SQL) as a valid JSON result with valid: false rather than as a protocol error. Protocol errors (missing required parameter, server fault) return an MCP error response.

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.

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":"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"]
}

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 all 10 GoSQLX style rules (L001–L010).

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 Desktop

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

{
  "mcpServers": {
    "gosqlx": {
      "command": "gosqlx-mcp",
      "env": {
        "GOSQLX_MCP_PORT": "8080"
      }
    }
  }
}

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)
    }
}

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)
}

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

Last Updated: 2026-03-09 Version: v1.10.0