Skip to main content

Connect an MCP client

Every client needs the same three settings:

SettingValue
TransportStreamable HTTP. The legacy HTTP+SSE transport is not supported.
URLhttps://mcp.urlquery.net/mcp
Headerx-apikey: <API_KEY>

There is no OAuth sign-in. The API key in the x-apikey header is the only credential, and the server uses it for every tool call, so the assistant sees what your account can see. Create a key under Settings → API keys on urlquery.net; see get an API key.

Keep the key out of config files​

Put the key in an environment variable and let the client read it, rather than writing it into a file that might be committed or synced:

export URLQUERY_API_KEY='<API_KEY>'

Add the line to your shell profile, or use your secret manager to set it, and start the client from that environment. The examples below read URLQUERY_API_KEY. Where a client cannot read environment variables, the page says so.

Use a separate API key for each client or agent. You can revoke one without breaking the others, and team members' keys act for the team. See authentication.

Claude Code​

Add the server for the current project and share the definition with your team through .mcp.json. The single quotes keep the variable unexpanded, so the file stores ${URLQUERY_API_KEY} and each person's own key is read at startup:

claude mcp add --transport http --scope project urlquery https://mcp.urlquery.net/mcp \
  --header 'x-apikey: ${URLQUERY_API_KEY}'

This writes .mcp.json in the project root, which you can also create by hand:

.mcp.json
{
  "mcpServers": {
    "urlquery": {
      "type": "http",
      "url": "https://mcp.urlquery.net/mcp",
      "headers": {
        "x-apikey": "${URLQUERY_API_KEY}"
      }
    }
  }
}

To use urlquery in every project instead, add it with --scope user. In user and local scope the definition is stored in ~/.claude.json; use double quotes there so the shell substitutes the key, and keep that file private:

claude mcp add --transport http --scope user urlquery https://mcp.urlquery.net/mcp \
  --header "x-apikey: ${URLQUERY_API_KEY}"

Check the connection with claude mcp list or claude mcp get urlquery, or run /mcp inside a session. The tools appear as mcp__urlquery__<tool>, for example mcp__urlquery__search_reports.

Approve submissions explicitly. All tools except submit_url only read. To let Claude Code use the read tools without asking while still confirming every new analysis, add permission rules to .claude/settings.json:

.claude/settings.json
{
  "permissions": {
    "allow": ["mcp__urlquery"],
    "ask": ["mcp__urlquery__submit_url"]
  }
}

ask rules take precedence over allow rules. To remove submissions entirely, put mcp__urlquery__submit_url under deny instead.

Codex​

Add the server to ~/.codex/config.toml, or to .codex/config.toml in a trusted project. env_http_headers maps a header name to the name of the environment variable that holds its value:

~/.codex/config.toml
[mcp_servers.urlquery]
url = "https://mcp.urlquery.net/mcp"
env_http_headers = { "x-apikey" = "URLQUERY_API_KEY" }

codex mcp add cannot set a custom header, so edit the file directly.

Check the connection with codex mcp list, or run /mcp in the Codex TUI.

Limit what Codex can do. To keep an assistant read-only, disable the submission tool:

~/.codex/config.toml
[mcp_servers.urlquery]
url = "https://mcp.urlquery.net/mcp"
env_http_headers = { "x-apikey" = "URLQUERY_API_KEY" }
disabled_tools = ["submit_url"]

Tool calls time out after 60 seconds by default. Large exports such as get_report_json on a big report can take longer; raise the limit with tool_timeout_sec = 120 if they time out.

VS Code (GitHub Copilot)​

Add the server to .vscode/mcp.json in the workspace, or to your user mcp.json with MCP: Open User Configuration. This version prompts for the key once and stores it in VS Code's secret storage:

.vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "urlquery-api-key",
      "description": "urlquery API key",
      "password": true
    }
  ],
  "servers": {
    "urlquery": {
      "type": "http",
      "url": "https://mcp.urlquery.net/mcp",
      "headers": {
        "x-apikey": "${input:urlquery-api-key}"
      }
    }
  }
}

To read the environment variable instead, drop inputs and set the header to "${env:URLQUERY_API_KEY}".

Check the connection with MCP: List Servers in the Command Palette. The urlquery tools are available in Copilot Chat agent mode.

Cursor​

Add the server to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

~/.cursor/mcp.json
{
  "mcpServers": {
    "urlquery": {
      "url": "https://mcp.urlquery.net/mcp",
      "headers": {
        "x-apikey": "${env:URLQUERY_API_KEY}"
      }
    }
  }
}

Check the connection in Cursor's MCP settings, where the server should show its tools. Connection errors are in the Output panel under MCP Logs.

Claude Desktop​

Custom connectors in Claude Desktop and claude.ai cannot send the x-apikey header. Use the open-source mcp-remote bridge, which runs locally through npx (Node.js required) and forwards requests with the header.

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

claude_desktop_config.json
{
  "mcpServers": {
    "urlquery": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.urlquery.net/mcp",
        "--transport",
        "http-only",
        "--header",
        "x-apikey:${URLQUERY_API_KEY}"
      ],
      "env": {
        "URLQUERY_API_KEY": "<API_KEY>"
      }
    }
  }
}
  • Write x-apikey:${URLQUERY_API_KEY} without a space after the colon. Some platforms split arguments on spaces.
  • Claude Desktop does not read your shell environment, so the key goes in the env block of this file. Keep the file private.
  • Restart Claude Desktop after saving. The urlquery tools appear under the tools menu in a new conversation.

opencode​

Add the server to opencode.json in the project, or to ~/.config/opencode/opencode.json for all projects:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "urlquery": {
      "type": "remote",
      "url": "https://mcp.urlquery.net/mcp",
      "headers": {
        "x-apikey": "{env:URLQUERY_API_KEY}"
      }
    }
  }
}

opencode writes environment variables as {env:NAME}, without a leading $. Restart opencode and check that the urlquery server and its tools are available.

Other clients​

Any client that supports remote MCP servers over Streamable HTTP with custom request headers works. Use the settings from the table at the top of this page, and look in the client's documentation for:

  • how to choose the Streamable HTTP transport. Some clients use a different field for it than for SSE, for example httpUrl instead of url;
  • how it reads environment variables or secrets in header values;
  • where it shows connection logs.

If a client supports only stdio servers, or only OAuth for remote servers, run it through mcp-remote as shown for Claude Desktop.

Test the connection​

A client can list the tools even when the API key is wrong, because the key is checked when a tool calls urlquery. Run one real call to confirm the key works:

Use urlquery to check the reputation of https://example.com/.

A verdict, including unknown, means the connection and the key work. Then try a search to confirm what your account can see:

Use urlquery to search for reports matching url.fqdn:example.com from the last 7 days.

Troubleshooting​

SymptomCause and fix
The client reports 401 or missing x-apikey header, or asks you to sign inThe header is not being sent. Check the header name is exactly x-apikey, and that the environment variable is set in the environment the client was started from. Restart the client after changing it.
The server is connected but every tool fails with "Invalid or missing API key" or "Access denied"The key is wrong, revoked, or has extra characters such as a trailing newline. Create a new key and update the variable.
A header value shows up literally as ${URLQUERY_API_KEY}The client does not expand that syntax in that file, or the variable is unset. Check the client's interpolation syntax in the sections above.
Connection fails with 405 Method Not AllowedThe client is using the legacy SSE transport, which opens the connection with a GET. Configure Streamable HTTP; in mcp-remote, pass --transport http-only.
Tools fail with "Rate limit exceeded"Your key's quota is used up. Wait for the reset, ask narrower questions, or see plans and features.
Reports or alerts you expect are missingThe server uses your account's visibility. Check the report visibility rules, and use a key from the account or team that owns the reports.
Large exports time outRaise the client's tool timeout, or use focused tools such as get_report and list_report_http_transactions instead of get_report_json.

Next steps​