AgentQL MCP Server for Windsurf: Setup & Config

What you can do with AgentQL in Windsurf

A compact URL-and-prompt interface for turning web pages into structured JSON inside MCP workflows.

• Collect video-result metadata as illustrated in the README.
• Use the same extraction tool across supported MCP hosts.

Before you start: AgentQL in Windsurf

• Node.js with npm / npx
• AgentQL API key
• An MCP-compatible host

The README also documents npm install -g agentql-mcp. Restart the host after adding its configuration. Development builds should replace, rather than duplicate, the default server entry.

AgentQL Windsurf configuration

1. Choose Windsurf configuration scope

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

2. Add AgentQL MCP Server to Windsurf

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

3. Check AgentQL MCP Server in Windsurf

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

{
  "mcpServers": {
    "agentql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "<API key from the AgentQL developer portal>"
      }
    }
  }
}

AgentQL tools available to Windsurf

AgentQL's stored tool list documents 1 tool; compare it with Windsurf's connected tool list, because the stored list is not a live check.

extract-web-data

After refreshing AgentQL in Windsurf settings, check Cascade's tool list for extract-web-data.

Extract JSON fields from a page URL using a natural-language description.

AgentQL: full stored tool descriptions

Troubleshooting AgentQL in Windsurf

• Check npx agentql-mcp (Node.js/npm) on the machine running Windsurf's MCP integration for AgentQL MCP Server; refresh MCP and inspect Cascade's tools.
• Check AGENTQL_API_KEY for AgentQL MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• AgentQL MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires an AgentQL API key.
• Known limitation: Only one extraction tool is documented.
• Known limitation: Pricing and usage limits are not stated in the README.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions