The Problem

Developers need a way to expose enterprise databases to AI agents and IDE tools without writing custom plumbing for each language or framework. Existing solutions either lock you into a single SDK or require extensive boilerplate to enforce safety, schema awareness, and access control.

What This Does

mcp-toolbox ships a Model Context Protocol (MCP) server that can be run as a container or a local Go binary. The server offers pre‑built generic tools (e.g., list_tables, execute_sql) and a framework for authoring custom tools that enforce structured queries and role‑based access.

  • Core server code lives under internal/ (≈ 713 files, 671 Go source files).
  • The CLI entry points are in cmd/internal/ – notably config.go, flags.go, and invoke/command.go.
  • Documentation, static assets, and the Hugo site are in .hugo/ and docs/.
  • CI pipelines and release automation sit in .github/workflows/ and .ci/.

How It Is Wired

Execution begins in cmd/internal/flags.go, which parses command‑line flags and hands control to cmd/internal/invoke/command.go. That file creates a Server struct (defined in internal/server/server.go) and calls Start() which:

  1. Loads configuration from cmd/internal/config.go – reads environment variables and optional YAML files.
  2. Initialises tool registries via internal/tools/registry.go, pulling built‑in tool definitions from internal/tools/prebuilt/.
  3. Starts the HTTP/MCP listener (internal/server/http.go) that routes MCP requests to the appropriate tool handler.

Tool handlers are simple Go functions that invoke the database driver (e.g., database/sql wrappers in internal/util/db/). The most connected JavaScript modules (e.g., internal/server/static/js/toolDisplay.js) are only used by the Hugo front‑end; they form a small import cycle with runTool.js but do not affect the Go server runtime.

The import graph shows 33 internal modules with only 9 import edges, indicating a low‑coupling core. Two cycles exist in the static JS layer; breaking them would reduce cognitive load but has no impact on server stability.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/mcp-toolbox
cd mcp-toolbox

# Build the Go binary (requires Go 1.22+)
go build -o mcp-toolbox ./cmd/internal

# Run the server (default port 8080)
./mcp-toolbox --config=./cmd/internal/config.yaml

Configuration – cmd/internal/config.go expects a YAML file with keys database_url, listen_port, and optional auth_token. The file format is documented in docs/en/documentation/configuration/pre-post-processing/go/adk/go.mod (the Go SDK example).

Docker – a ready‑to‑use image can be built with the provided Dockerfile:

docker build -t mcp-toolbox:latest .
docker run -p 8080:8080 -e DATABASE_URL=postgres://... mcp-toolbox:latest

The server can be queried via any MCP‑compatible client (Gemini CLI, Claude Code, etc.) as described in the official docs.

Real‑World Use

A data‑science team runs the container in their VPC, exposing execute_sql to an internal LLM that drafts analytical queries. The LLM sends an MCP request; the server validates the query against the allowed_schemas list in config.yaml, executes it with the Go database/sql driver, and returns results in a JSON‑MCP payload. No custom SDK code is required beyond the standard MCP client.

Code Health & Issues

  • Critical – Secrets in .github/workflows/docs_preview_deploy_cf.yaml (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID).
  • High – CI does not run the test suite; add a go test ./... step to existing workflows.
  • Medium – Base images in Dockerfile are unpinned; replace golang:1 and gcr.io/distroless/cc-debian12:nonroot with digested tags.
  • Medium – No dependency‑vulnerability scan; add dependency-review-action or osv-scanner.
  • Medium – Large binaries (edit-headers.gif, run-tool.gif) should be moved to Git LFS or external storage.
  • Medium – Checkout step keeps the token; set persist-credentials: false in deploy_dev_docs_to_cf.yaml.
  • Low – Workflow jobs lack timeout-minutes; add reasonable limits to avoid hung runs.

Additional static findings: 51 deep‑nesting hotspots (e.g., internal/server/static/js/runTool.js), duplicated 6‑line blocks across 789 files, and six oversized files (e.g., cmd/internal/config_test.go with 2 288 lines). Refactoring these will improve maintainability.

The Bottom Line

mcp-toolbox delivers a functional MCP server with solid Go foundations and multi‑language SDKs, making it a practical bridge between AI agents and databases. Production use should first address the critical secret exposure and add proper test execution in CI; after that, the codebase is stable enough for extension, though the JavaScript front‑end contains avoidable cycles and the Go test suite is large and deeply nested. Suitable for teams that need an out‑of‑the‑box MCP endpoint and are comfortable managing Go builds and Docker deployments.