MCP Alchemy for Windsurf: Setup & Config

What you can do with MCP Alchemy in Windsurf

Combine schema exploration with SQL execution and an optional path to full, unabridged result sets.

• Narrow a large table inventory using a name substring.
• Use the companion file integration for analysis that needs unabridged query results.

Before you start: MCP Alchemy in Windsurf

• uv installation providing uvx
• A database reachable through the chosen SQLAlchemy URL
• Driver dependency matching the database if not using the SQLite example

The version pin and argument sequence reproduce the SQLite README example. For another engine, use its documented --with dependency and matching DB_URL. The remaining environment entries are optional settings listed in the README; the full-result path is meaningful with claude-local-files configured.

MCP Alchemy Windsurf configuration

1. Choose Windsurf configuration scope

   For MCP Alchemy, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add MCP Alchemy to Windsurf

   Use the mcp-alchemy entry below in mcpServers. Keep MCP Alchemy's documented stdio connection fields and your other Windsurf entries.

3. Check MCP Alchemy in Windsurf

   MCP Alchemy: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-alchemy": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-alchemy==2025.8.15.91819",
        "--refresh-package",
        "mcp-alchemy",
        "mcp-alchemy"
      ],
      "env": {
        "DB_URL": "<required SQLAlchemy connection URL; use SQLite for this driver-free example>",
        "CLAUDE_LOCAL_FILES_PATH": "<optional directory used by the full-result companion integration>",
        "EXECUTE_QUERY_MAX_CHARS": "<optional character ceiling for query responses>",
        "DB_ENGINE_OPTIONS": "<optional engine overrides encoded as a JSON string>"
      }
    }
  }
}

MCP Alchemy tools available to Windsurf

MCP Alchemy's stored tool list documents 4 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

schema_definitions

After refreshing MCP Alchemy in Windsurf settings, check Cascade's tool list for schema_definitions.

filter_table_names

After refreshing MCP Alchemy in Windsurf settings, check Cascade's tool list for filter_table_names.

Narrow the table inventory to names containing the requested text.

all_table_names

After refreshing MCP Alchemy in Windsurf settings, check Cascade's tool list for all_table_names.

execute_query

After refreshing MCP Alchemy in Windsurf settings, check Cascade's tool list for execute_query.

Run SQL with optional parameter values and display rows in a vertical layout.

MCP Alchemy: full stored tool descriptions

Troubleshooting MCP Alchemy in Windsurf

• Check uvx --from (from uv, for Python tools) on the machine running Windsurf's MCP integration for MCP Alchemy; refresh MCP and inspect Cascade's tools.
• Check CLAUDE_LOCAL_FILES_PATH, DB_ENGINE_OPTIONS, DB_URL, EXECUTE_QUERY_MAX_CHARS for MCP Alchemy; do not bypass a Windsurf permission error with a broad administrator token.
• MCP Alchemy uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: The database-specific examples generally need an additional driver beyond the SQLite setup.
• Known limitation: An ordinary query response is shortened once it reaches the configured character ceiling.
• Known limitation: Default autocommit means queries are committed automatically rather than awaiting a later commit.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions