From adc077fe825e4c6c611ef3125faaf71617a5a3c6 Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Tue, 6 Oct 2026 15:15:29 +0300 Subject: [PATCH 1/6] chore: update readme --- README.md | 102 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 60 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index c903f60..54105ae 100644 --- a/README.md +++ b/README.md @@ -80,15 +80,17 @@ scraping infrastructure from scratch. Common scenarios: 1. **Create a free account** at [dashboard.decodo.com](https://dashboard.decodo.com/) – up to 2K free requests, no credit card required. -2. **Get your authentication token.** Obtain a Web Scraping API basic authentication token from the dashboard. +2. **Get your API key.** Copy your Web Data API key from your Web Data API subscription on the + [dashboard](https://dashboard.decodo.com/playground). Older plans have a basic authentication + token, which also works (see [Authentication](#authentication)). 3. **Download Node.js 18+** from https://nodejs.org. -4. **Get MCP client** like Claude Desktop, Cursor, Windsurf or other MCP-compatible - tools. +4. **Get MCP client** like Claude Desktop, Cursor, Windsurf or other MCP-compatible tools. 5. **Configure the MCP server** in your AI client (see configuration examples below). -## Connecting to [Decodo's MCP server](https://mcp.decodo.com/mcp) +## Connecting to [Decodo's MCP server](https://mcp.decodo.com/mcp) -Open your preferred MCP client and add the following configuration (see examples for Claude Code, Cursor, Windsurf bellow): +Open your preferred MCP client and add the following configuration (see examples for Claude Code, +Cursor, Windsurf bellow): ``` { @@ -96,14 +98,24 @@ Open your preferred MCP client and add the following configuration (see examples "Decodo": { "url": "https://mcp.decodo.com/mcp", "headers": { - "Authorization": "Basic " + "Authorization": "Bearer " } } } } ``` +### Authentication + +| Credential | Where to get it | Hosted server header | Local server env | +| -------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------- | +| **API key** (recommended) | Web Data API subscription on the [dashboard](https://dashboard.decodo.com/) | `Authorization: Bearer ` | `SCRAPER_API_TOKEN=` | +| **Basic authentication token** (older plans) | Web Scraping API page on the dashboard | `Authorization: Basic ` | `SCRAPER_API_TOKEN=` | + +The local server reads either credential from `SCRAPER_API_TOKEN` and works out which one it got. + ### Claude Desktop + 1. Open Claude Desktop → Settings → Developer → Edit Config. 2. Add to claude_desktop_config.json: @@ -114,35 +126,40 @@ Open your preferred MCP client and add the following configuration (see examples "command": "npx", "args": ["-y", "@decodo/mcp-server"], "env": { - "SCRAPER_API_TOKEN": "", + "SCRAPER_API_TOKEN": "", "TOOLSETS": "web,ai" } } } } ``` + 3. Save and restart Claude Desktop. ### Cursor - 1. Open Settings → MCP. - 2. Click Add a new global MCP server (opens mcp.json). - 3. Add the same configuration as above. - 4. Save — look for a green status indicator next to Decodo. + +1. Open Settings → MCP. +2. Click Add a new global MCP server (opens mcp.json). +3. Add the same configuration as above. +4. Save — look for a green status indicator next to Decodo. ### Windsurf - 1. Open Settings → Windsurf Settings. - 2. Scroll to Cascade → Add custom server + (opens mcp_config.json). - 3. Add the same configuration as above. - 4. Save and restart Windsurf. + +1. Open Settings → Windsurf Settings. +2. Scroll to Cascade → Add custom server + (opens mcp_config.json). +3. Add the same configuration as above. +4. Save and restart Windsurf. ## Test your setup + Once connected, try this prompt in your client: - ▎ "Scrape the titles of the top 5 articles from Hacker News" +▎ "Scrape the titles of the top 5 articles from Hacker News" + +You should get a structured list back within seconds. If you see an auth error, double-check your +API key on the dashboard. -You should get a structured list back within seconds. If you see an auth error, double-check your token from the dashboard. ## Optional: enable specific toolsets - # Running the MCP server locally @@ -193,7 +210,7 @@ this: "command": "node", "args": ["/Users/your.user/projects/decodo-mcp/build/index.js"], "env": { - "SCRAPER_API_TOKEN": "" + "SCRAPER_API_TOKEN": "" } } } @@ -211,7 +228,7 @@ comma-separated list via the `toolsets` query parameter: "Decodo MCP Server": { "url": "https://mcp.decodo.com/mcp?toolsets=web,ai", "headers": { - "Authorization": "Basic " + "Authorization": "Bearer " } } ``` @@ -267,23 +284,23 @@ The server exposes the following tools: The following parameters are inferred from user prompts: -| Parameter | Description | -| --------------- | ----------------------------------------------------------------------------------------------------- | -| `jsRender` | Renders target URL in a headless browser. | -| `geo` | Sets the country from which the request will originate. | -| `locale` | Sets the locale of the request. | -| `tokenLimit` | Truncates the response content up to this limit. Useful if the context window is small. | -| `prompt` | Prompt to send to AI tools (`chatgpt`, `perplexity`). | -| `search` | Activates ChatGPT's web search functionality (`chatgpt` only). | -| `xhr` | When true, includes XHR or fetch responses in the scrape result where supported (e.g. `tiktok_post`). | +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `jsRender` | Renders target URL in a headless browser. | +| `geo` | Sets the country from which the request will originate. | +| `locale` | Sets the locale of the request. | +| `tokenLimit` | Truncates the response content up to this limit. Useful if the context window is small. | +| `prompt` | Prompt to send to AI tools (`chatgpt`, `perplexity`). | +| `search` | Activates ChatGPT's web search functionality (`chatgpt` only). | +| `xhr` | When true, includes XHR or fetch responses in the scrape result where supported (e.g. `tiktok_post`). | | `deviceType` | Device type to emulate (`desktop`, `mobile`, `tablet`). Parsed targets are stricter: Amazon tools are desktop-only so they omit it, and `bing_search`/`google_ai_mode` accept `desktop` and `mobile` only. | -| `domain` | Domain to use for the request (e.g., `amazon.com`, `amazon.co.uk`, `bing.com`). | -| `pageFrom` | Starting page number for pagination. | -| `deliveryZip` | ZIP code for delivery location (Target, Walmart). | -| `storeId` | Store ID for local inventory (Walmart). | -| `country` | Country for TikTok Shop requests. | -| `limit` | Maximum number of results to return (e.g., YouTube channel videos). | -| `language_code` | Language code for subtitles (e.g., `en`, `es`). | +| `domain` | Domain to use for the request (e.g., `amazon.com`, `amazon.co.uk`, `bing.com`). | +| `pageFrom` | Starting page number for pagination. | +| `deliveryZip` | ZIP code for delivery location (Target, Walmart). | +| `storeId` | Store ID for local inventory (Walmart). | +| `country` | Country for TikTok Shop requests. | +| `limit` | Maximum number of results to return (e.g., YouTube channel videos). | +| `language_code` | Language code for subtitles (e.g., `en`, `es`). | ## Examples @@ -319,13 +336,14 @@ Scrape hacker news, return full content. ## Use with Decodo agent skills -This server gives your agent the scraping *tools*. [`Decodo/agent-skills`](https://github.com/Decodo/agent-skills) -teaches it **when** to reach for them, **which** surface to use, and **how** to call it — so the agent -picks the right tool and parameters on its own instead of guessing. +This server gives your agent the scraping _tools_. +[`Decodo/agent-skills`](https://github.com/Decodo/agent-skills) teaches it **when** to reach for +them, **which** surface to use, and **how** to call it — so the agent picks the right tool and +parameters on its own instead of guessing. -The skills route across the `decodo` CLI, this hosted MCP server, and the raw HTTP API, and fall back -to the MCP server automatically when no shell is available. Pairing the two gives your agent both the -execution layer (this server) and the decision layer (the skills) in a single setup. +The skills route across the `decodo` CLI, this hosted MCP server, and the raw HTTP API, and fall +back to the MCP server automatically when no shell is available. Pairing the two gives your agent +both the execution layer (this server) and the decision layer (the skills) in a single setup. **Quick start** (Claude Code): From 0ccfe0dfd4a63eb4f990e66fef5c2303cddef3f0 Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Tue, 6 Oct 2026 16:39:15 +0300 Subject: [PATCH 2/6] chore: update url --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 54105ae..066ae69 100644 --- a/README.md +++ b/README.md @@ -81,8 +81,8 @@ scraping infrastructure from scratch. Common scenarios: 1. **Create a free account** at [dashboard.decodo.com](https://dashboard.decodo.com/) – up to 2K free requests, no credit card required. 2. **Get your API key.** Copy your Web Data API key from your Web Data API subscription on the - [dashboard](https://dashboard.decodo.com/playground). Older plans have a basic authentication - token, which also works (see [Authentication](#authentication)). + [dashboard](https://dashboard.decodo.com/web-data/playground). Older plans have a basic + authentication token, which also works (see [Authentication](#authentication)). 3. **Download Node.js 18+** from https://nodejs.org. 4. **Get MCP client** like Claude Desktop, Cursor, Windsurf or other MCP-compatible tools. 5. **Configure the MCP server** in your AI client (see configuration examples below). From 6c04c5978f723235baeb88341fbb3404a80252c4 Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Tue, 6 Oct 2026 17:17:45 +0300 Subject: [PATCH 3/6] chore: bump server versions --- package-lock.json | 4 ++-- package.json | 2 +- server.json | 4 ++-- src/server/__tests__/server-registration.test.ts | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/package-lock.json b/package-lock.json index 0e3ad4f..4848993 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@decodo/mcp-server", - "version": "1.2.5", + "version": "1.2.6", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@decodo/mcp-server", - "version": "1.2.5", + "version": "1.2.6", "license": "ISC", "dependencies": { "@decodo/sdk-ts": "^2.3.0", diff --git a/package.json b/package.json index 01d2f50..2505566 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@decodo/mcp-server", - "version": "1.2.5", + "version": "1.2.6", "description": "Decodo MCP Server", "bin": { "decodo-mcp": "./build/index.js" diff --git a/server.json b/server.json index 7ef2dd5..efa5bf2 100644 --- a/server.json +++ b/server.json @@ -7,13 +7,13 @@ "url": "https://github.com/Decodo/mcp-server", "source": "github" }, - "version": "1.2.5", + "version": "1.2.6", "packages": [ { "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@decodo/mcp-server", - "version": "1.2.5", + "version": "1.2.6", "transport": { "type": "stdio" } diff --git a/src/server/__tests__/server-registration.test.ts b/src/server/__tests__/server-registration.test.ts index a8616b8..d06dc45 100644 --- a/src/server/__tests__/server-registration.test.ts +++ b/src/server/__tests__/server-registration.test.ts @@ -25,7 +25,7 @@ describe('Server registration', () => { expect(McpServer).toHaveBeenCalledWith({ name: 'decodo', - version: '1.2.5', + version: '1.2.6', }); }); From b6ba8a1c451fbcfeebf35e39c07a65dc64d93bdb Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Wed, 7 Oct 2026 14:53:40 +0300 Subject: [PATCH 4/6] clearer error message + readme --- README.md | 8 ++++---- src/index.ts | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 066ae69..a6ba25a 100644 --- a/README.md +++ b/README.md @@ -107,10 +107,10 @@ Cursor, Windsurf bellow): ### Authentication -| Credential | Where to get it | Hosted server header | Local server env | -| -------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------- | -| **API key** (recommended) | Web Data API subscription on the [dashboard](https://dashboard.decodo.com/) | `Authorization: Bearer ` | `SCRAPER_API_TOKEN=` | -| **Basic authentication token** (older plans) | Web Scraping API page on the dashboard | `Authorization: Basic ` | `SCRAPER_API_TOKEN=` | +| Credential | Where to get it | Hosted server header | Local server env | +| -------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------- | +| **API key** (recommended) | Web Data API subscription on the [dashboard](https://dashboard.decodo.com/web-data/playground) | `Authorization: Bearer ` | `SCRAPER_API_TOKEN=` | +| **Basic authentication token** (older plans) | Web Scraping API page on the dashboard | `Authorization: Basic ` | `SCRAPER_API_TOKEN=` | The local server reads either credential from `SCRAPER_API_TOKEN` and works out which one it got. diff --git a/src/index.ts b/src/index.ts index 31aa69a..00663eb 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,7 +19,7 @@ const parseEnvsOrExit = () => { const sapiAuth = credentialFromValue(process.env['SCRAPER_API_TOKEN'] as string); if (!sapiAuth) { - console.error('env SCRAPER_API_TOKEN missing'); + console.error('env SCRAPER_API_TOKEN missing: set your API key or basic auth token'); process.exit(1); } From ba6b544d766ca9632360557b99c276232a361b19 Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Wed, 7 Oct 2026 15:40:05 +0300 Subject: [PATCH 5/6] update message --- src/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/index.ts b/src/index.ts index 00663eb..ef9d362 100644 --- a/src/index.ts +++ b/src/index.ts @@ -11,7 +11,7 @@ const parseEnvsOrExit = () => { for (const envKey of envs) { if (!process.env[envKey]) { - console.error(`env ${envKey} missing`); + console.error(`env ${envKey} missing: set your API key or basic auth token`); process.exit(1); } } From 796be665cb218452b6d9c3f92b089bc106bca0a6 Mon Sep 17 00:00:00 2001 From: "aiste.grigaliunaite@decodo.com" Date: Thu, 8 Oct 2026 13:56:50 +0300 Subject: [PATCH 6/6] update cursor setup --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a6ba25a..f335e35 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Decodo MCP Server [![](https://dcbadge.limes.pink/api/server/https://discord.gg/Ja8dqKgvbZ)](https://discord.gg/Ja8dqKgvbZ) -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=Decodo&config=eyJ1cmwiOiJodHRwczovL21jcC5kZWNvZG8uY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJhc2ljIDx3ZWJfYWR2YW5jZWRfdG9rZW4%2BIn19) +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=Decodo&config=eyJ1cmwiOiJodHRwczovL21jcC5kZWNvZG8uY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8YXBpX2tleT4ifX0%3D)