Superbash
SearchUser Hub

Decodo Web Scraping · Tutorial 03

Connect Decodo to any MCP-compatible AI agent

Connect Decodo to Codex, Claude Code, Cursor, Windsurf, VS Code, Hermes, or another MCP-compatible agent, then verify one harmless scrape.

Official Decodo MCP Server documentation showing its purpose, supported data types, and navigation for client setup and toolsets.
Reading time
20 min
Last updated
August 2026

0 of 5 complete

Complete & next →

Essentials · Step 3 of 5 · View the route

Last tested and updated: August 25, 2026

MCP lets a compatible assistant discover and call Decodo tools without you writing the HTTP request by hand. Connection is not the final test. The final test is seeing a named Decodo tool run and return the expected fields.

Before you start

You need:

  1. A Decodo Web Scraping API account.
  2. Its Basic authentication token. This is not a proxy username/password and not a Bearer token.
  3. An MCP client such as ChatGPT desktop, Codex CLI, Claude Code, Cursor, Windsurf, Hermes, or another client that supports remote or stdio servers.
  4. Node.js 18 or newer if you use the local npm package.

Use Ron’s Decodo partner link if you want to support Superbash Learn. Plan details change; verify current allowance and price in your dashboard.

Step 1: copy the correct token

Open Decodo Dashboard, enter Web Scraping API, and copy the Basic authentication token from the API area.

Do not paste it into:

  • a chat prompt;
  • a screenshot;
  • a public repository;
  • a shared Skill file.

If exposed, rotate it. Deleting a committed token does not make the old token private again.

Step 2A: add the hosted MCP server

Clients that support remote MCP servers can use:

The JSON below is a reference for clients that use the common mcpServers format. Codex, VS Code, and Hermes use different configuration syntax; Step 4 gives the exact destination for each client.

{
  "mcpServers": {
    "Decodo": {
      "url": "https://mcp.decodo.com/mcp?toolsets=web,search",
      "headers": {
        "Authorization": "Basic <basic_auth_token>"
      }
    }
  }
}

Replace only <basic_auth_token>. Keep Basic and one space before the token.

Official Decodo documentation showing the remote MCP server URL and Authorization Basic header configuration.
Official Decodo MCP configuration captured August 19, 2026. Client settings differ, but remote authentication uses the Basic scheme.

Step 2B: add the local npm server

For clients that launch stdio MCP servers, use Decodo’s official package:

{
  "mcpServers": {
    "Decodo": {
      "command": "npx",
      "args": ["-y", "@decodo/mcp-server"],
      "env": {
        "SCRAPER_API_TOKEN": "<basic_auth_token>",
        "TOOLSETS": "web,search"
      }
    }
  }
}

Save the file, then restart or reload MCP in the client.

The value of SCRAPER_API_TOKEN is the raw Basic token. Do not add the word Basic inside this environment variable. The hosted HTTP route is different: its complete Authorization header must begin with Basic .

Step 3: understand the universal Decodo setup

The Decodo side of the setup is universal across MCP-compatible AI agent environments. Every client needs the same five decisions:

  1. Name the server decodo so it is easy to recognize.
  2. Choose one transport: hosted HTTP or the local stdio package. Do not configure both for the first test.
  3. Authenticate correctly. Local stdio receives the raw token as SCRAPER_API_TOKEN; hosted HTTP receives Authorization: Basic <basic_auth_token>.
  4. Start with TOOLSETS=web,search so the agent sees a focused tool catalog.
  5. Reload the client and run the same one-request smoke test in Step 6.

Only the client wrapper changes. Each environment has its own file location, configuration dialect, secret mechanism, and status command:

Configuration familyClients in this lessonMain difference
TOMLChatGPT desktop, Codex CLI, Codex IDE extensionUses [mcp_servers.decodo] in Codex configuration
mcpServers JSONClaude Code, Cursor, Windsurf, and many other clientsUses a named server inside an mcpServers object
servers JSONVS CodeUses a top-level servers object and can prompt securely for secrets
YAMLHermes AgentUses mcp_servers in ~/.hermes/config.yaml

Pick your client below and follow only that subsection.

Step 4: configure your AI agent client

Codex: ChatGPT desktop, CLI, or IDE extension

ChatGPT desktop, Codex CLI, and the Codex IDE extension share MCP configuration on the same host.

  1. Save SCRAPER_API_TOKEN as a user environment variable through your operating system or secret manager.
  2. Add this block to ~/.codex/config.toml:
[mcp_servers.decodo]
command = "npx"
args = ["-y", "@decodo/mcp-server"]
env_vars = ["SCRAPER_API_TOKEN"]

[mcp_servers.decodo.env]
TOOLSETS = "web,search"
  1. Restart ChatGPT desktop or the IDE extension so it receives the environment variable.
  2. Run codex mcp list in the CLI or open /mcp in Codex. Confirm that decodo is connected and exposes tools.

You can instead use a project-scoped .codex/config.toml in a trusted project. Avoid passing a long-lived token through codex mcp add --env; the value can remain in shell history and is written into Codex configuration.

ChatGPT web is a separate case. It does not read local Codex configuration. Web chats use remote MCP-backed tools supplied through installed plugins, so this setup does not automatically add Decodo to chatgpt.com.

Claude Code

  1. Save SCRAPER_API_TOKEN in your operating system environment.
  2. Create .mcp.json in the project root and add:
{
  "mcpServers": {
    "decodo": {
      "command": "npx",
      "args": ["-y", "@decodo/mcp-server"],
      "env": {
        "SCRAPER_API_TOKEN": "${SCRAPER_API_TOKEN}",
        "TOOLSETS": "web,search"
      }
    }
  }
}
  1. Start Claude Code and approve the project server after reviewing it.
  2. Run claude mcp list or open /mcp and confirm that the server connected.

Project scope is useful for a shared server definition because the token remains in each teammate’s environment. Use claude mcp add --scope user if you want a private server available across projects, but do not put the token directly in a shared command or repository.

Cursor

  1. Open Cursor’s MCP settings.
  2. Choose global configuration for a personal setup or project configuration for a team setup. The files are ~/.cursor/mcp.json and .cursor/mcp.json, respectively.
  3. Add the local mcpServers block from Step 2B.
  4. Keep any file containing the real token private and out of version control. If your managed Cursor environment supplies secrets, pass SCRAPER_API_TOKEN through that mechanism instead.
  5. Reload MCP, open Available Tools, and confirm that the Decodo tools appear. The Cursor CLI reads the same MCP configuration as the IDE.

Windsurf or legacy Cascade

  1. Open the MCPs icon in Cascade, or go to Devin Settings > Cascade > MCP Servers.
  2. Edit the raw file at ~/.codeium/windsurf/mcp_config.json.
  3. Add this secret-safe local configuration:
{
  "mcpServers": {
    "decodo": {
      "command": "npx",
      "args": ["-y", "@decodo/mcp-server"],
      "env": {
        "SCRAPER_API_TOKEN": "${env:SCRAPER_API_TOKEN}",
        "TOOLSETS": "web,search"
      }
    }
  }
}
  1. Refresh MCP servers, open the Decodo server settings, and enable only the tools you intend to use.

Current Windsurf documentation is maintained under Devin Desktop. Its legacy Cascade configuration still uses the path and interpolation syntax shown above; newer Devin Local Agent tabs use Devin CLI configuration instead.

VS Code with an agent extension

  1. Open the Command Palette and run MCP: Open User Configuration for a private global setup, or create .vscode/mcp.json for the current workspace.
  2. Add this configuration. VS Code prompts for the token and stores it securely instead of placing it in the file:
{
  "inputs": [
    {
      "type": "promptString",
      "id": "decodo-token",
      "description": "Decodo Web Scraping API Basic token",
      "password": true
    }
  ],
  "servers": {
    "decodo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@decodo/mcp-server"],
      "env": {
        "SCRAPER_API_TOKEN": "${input:decodo-token}",
        "TOOLSETS": "web,search"
      }
    }
  }
}
  1. Start the server and review VS Code’s trust prompt.
  2. Run MCP: List Servers, select decodo, and inspect its tools or output log.

Hermes Agent

  1. Put the raw token in Hermes’ local secret file:
# ~/.hermes/.env
SCRAPER_API_TOKEN=PASTE_YOUR_BASIC_AUTH_TOKEN_HERE
  1. Add this block to ~/.hermes/config.yaml:
mcp_servers:
  decodo:
    command: "npx"
    args: ["-y", "@decodo/mcp-server"]
    env:
      SCRAPER_API_TOKEN: "${SCRAPER_API_TOKEN}"
      TOOLSETS: "web,search"
    enabled: true
  1. Run hermes mcp test decodo, then hermes mcp list.
  2. Start a new Hermes session or run /reload-mcp in the current session.

For local and hosted Hermes configurations plus recommended tool choices, use the Decodo MCP + Hermes Agent companion guide.

Other JSON-based MCP clients

Open the client’s MCP configuration, identify whether it expects mcpServers or servers, and translate the Step 2 definition into that wrapper. Preserve the Decodo command or URL, token semantics, and toolsets exactly. Then use the client’s reload or server-status control to confirm that the named Decodo tools appear.

Step 5: keep the tool catalog small

Start with web,search. Add ecommerce, social_media, or ai only when the job needs them.

Official Decodo MCP documentation showing toolsets and the web and search tools they enable.
Official toolset table captured August 19, 2026. When no toolset filter is supplied, all tools are registered.

Step 6: run a one-request smoke test

Use a harmless public target:

Use Decodo's scrape_as_markdown tool on https://news.ycombinator.com/.
Return the first five story titles and links.
Use exactly one Decodo request. Do not fall back to another web tool.

Check three things:

  1. The client names scrape_as_markdown or clearly shows the Decodo tool call.
  2. Five linked items appear.
  3. The assistant did not silently use ordinary search or browser tools.

Step 7: install or write routing instructions, never credentials

A reusable Skill should hold procedure. Decodo now publishes official Agent Skills for common routing and price-monitoring workflows; the next lesson explains when and how to install them. If you write your own procedure, keep it narrow:

Use the narrowest Decodo tool for the target.
Return source URL, observed date, requested geography, and requested fields.
Leave missing values null. Do not infer price, stock, author, or date.
Stop after one failed retry. Report total Decodo calls.

Keep the token in client secrets or environment configuration.

Next: teach a coding agent when to use Decodo with Agent Skills.

Troubleshooting

401 Unauthorized

  • Verify this is the Web Scraping API Basic token.
  • Keep Authorization: Basic ..., not Bearer.
  • Remove accidental spaces or line breaks.
  • Rotate a leaked token.

No Decodo tools appear

  • Restart the MCP client after saving configuration.
  • For local setup, confirm node --version is 18+ and npx -y @decodo/mcp-server can launch.
  • Validate JSON/YAML indentation and commas.
  • Test with only web before adding toolsets.

Assistant uses another web tool

  • Name the Decodo tool in the prompt.
  • Say “do not fall back.”
  • Reduce enabled toolsets.
  • Stop the run if the Decodo call is not visible.

Official references