AgentQL MCP Server for Claude Code: Setup & Config

What you can do with AgentQL in Claude Code

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

• Extract named fields from a page into JSON.
• Use the same extraction tool across supported MCP hosts.

Before you start: AgentQL in Claude Code

• 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 Claude Code configuration

1. Choose Claude Code configuration scope

   For AgentQL MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add AgentQL MCP Server to Claude Code

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

3. Check AgentQL MCP Server in Claude Code

   AgentQL MCP Server: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'agentql-mcp' '{"type":"stdio","command":"npx","args":["-y","agentql-mcp"],"env":{"AGENTQL_API_KEY":"<API key from the AgentQL developer portal>"}}'

AgentQL tools available to Claude Code

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

extract-web-data

For AgentQL's extract-web-data, review the permission request and arguments in Claude Code before approval.

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

AgentQL: full stored tool descriptions

Troubleshooting AgentQL in Claude Code

• If AgentQL MCP Server fails to start, check npx agentql-mcp (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• AgentQL MCP Server: check AGENTQL_API_KEY; keep credentials out of shared .mcp.json.
• AgentQL MCP Server uses stdio here: Claude Code 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 Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions