From ad96f3a2860b2c629068675cf207ff15cf1e3bc9 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 25 Mar 2026 15:35:57 +0100 Subject: [PATCH 01/10] docs: add Claude Desktop setup and troubleshooting page for Apify MCP Add a dedicated page for Claude Desktop users covering three setup methods (one-click .mcpb, remote server, local stdio), troubleshooting common issues, and known limitations. Cross-reference from the main MCP page. Closes #2368 Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integrations/ai/claude-desktop.md | 196 ++++++++++++++++++ sources/platform/integrations/ai/mcp.md | 6 + 2 files changed, 202 insertions(+) create mode 100644 sources/platform/integrations/ai/claude-desktop.md diff --git a/sources/platform/integrations/ai/claude-desktop.md b/sources/platform/integrations/ai/claude-desktop.md new file mode 100644 index 0000000000..2039dde52a --- /dev/null +++ b/sources/platform/integrations/ai/claude-desktop.md @@ -0,0 +1,196 @@ +--- +title: Claude Desktop integration +sidebar_label: Claude Desktop +description: Set up the Apify MCP server in Claude Desktop with remote or local configuration, and troubleshoot common connection issues. +sidebar_position: 1.5 +slug: /integrations/claude-desktop +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. + +## Prerequisites + +- An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations) +- [Claude Desktop](https://claude.ai/download) installed +- [Node.js](https://nodejs.org/) version 18 or higher (only required for [local stdio setup](#local-stdio-server)) + +## Connect to Apify + +Choose one of the following methods, from simplest to most flexible. + +### One-click installation (recommended) + +Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. + +:::caution Connector directory + +If you found Apify through the Claude Desktop connector directory, the automatic install may fail silently or show an "Unable to connect to extension server" error. Use the `.mcpb` file above or the [manual configuration](#remote-server-manual-configuration) below instead. + +::: + +### Remote server (manual configuration) + +The remote server at `https://mcp.apify.com` is the simplest manual setup - no local dependencies required. + +1. Open Claude Desktop. +1. Go to **Settings** > **Developer** > **Edit Config**. +1. Add the Apify MCP server configuration: + + + + +```json +{ + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } + } +} +``` + +On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure. + + + + +```json +{ + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. + + + + +:::note Older Claude Desktop versions + +If your version of Claude Desktop does not support the `url` field, use the `mcp-remote` bridge package: + +```json +{ + "mcpServers": { + "apify": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.apify.com/sse"] + } + } +} +``` + +This requires Node.js version 18 or higher. + +::: + +### Local stdio server + +Run the MCP server locally for development, testing, or when you need offline access. This method requires Node.js. + +1. Open Claude Desktop. +1. Go to **Settings** > **Developer** > **Edit Config**. +1. Add the following configuration: + +```json +{ + "mcpServers": { + "actors-mcp-server": { + "command": "npx", + "args": ["-y", "@apify/actors-mcp-server"], + "env": { + "APIFY_TOKEN": "" + } + } + } +} +``` + +Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. + +:::info Output schema inference + +The local stdio server does not support output schema inference for structured Actor results. Use the [remote server](#remote-server-manual-configuration) to get automatic output schemas with field-level type information. + +::: + +## Verify the connection + +1. Restart Claude Desktop after saving configuration changes. +1. Open a new conversation. +1. Look for the hammer icon in the chat input area - this indicates MCP tools are available. +1. Click the hammer icon to confirm Apify tools appear in the list. +1. Test with a prompt like: "Search for web scraping Actors on Apify." + +## Troubleshooting + +### Tools not loading + +- **Restart Claude Desktop.** Configuration changes only take effect after a restart. +- **Check the config file location.** Verify you edited the correct file: + - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` + - Windows: `%APPDATA%\Claude\claude_desktop_config.json` +- **Validate JSON syntax.** Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. + +### "Unable to connect" error + +- **Verify the server URL.** For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. +- **Check your network.** Ensure your firewall or VPN is not blocking the connection. +- **For local stdio setup:** Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. +- **Try the remote server.** If the local server fails, switch to the [remote server configuration](#remote-server-manual-configuration) to rule out local environment issues. + +### Corrupted npx cache + +A stale or corrupted npx cache can prevent the local server from starting. Clear the cache and retry: + +- macOS and Linux: + + ```bash + rm -rf ~/.npm/_npx + ``` + +- Windows: + + ```bash + rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx + ``` + +After clearing the cache, restart Claude Desktop to re-download the server package. + +### Authentication errors + +- **Check your API token.** Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. +- **For local stdio setup:** Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. +- **For remote OAuth:** Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. + +### Check Claude Desktop logs + +If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors: + +- macOS: `~/Library/Logs/Claude/` +- Linux: `~/.config/Claude/logs/` +- Windows: `%APPDATA%\Claude\logs\` + +Look for files with `mcp` in the name for server-specific error messages. + +## Known limitations + +- **Connector directory:** The Claude Desktop connector directory may not install Apify correctly. Use the [`.mcpb` file](#one-click-installation-recommended) or [manual configuration](#remote-server-manual-configuration) instead. +- **Cowork mode:** Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server. +- **Transport inconsistencies:** Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. + +## Next steps + +- [Apify MCP server](/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits +- [Apify MCP server configurator](https://mcp.apify.com) - Select tools visually and copy configuration +- [Apify MCP server on GitHub](https://github.com/apify/apify-mcp-server) - Report bugs and suggest features diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 3842045fc5..50113c5a55 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -233,6 +233,8 @@ To manually configure Apify's MCP server for Claude Desktop: Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). +For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/integrations/claude-desktop). + @@ -431,6 +433,10 @@ documentation queries. If you exceed this limit, you'll receive a `429` response ## Troubleshooting +:::tip Claude Desktop issues +For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting). +::: + ##### Authentication errors - _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). Without a valid token, the server cannot start Actor runs. From 84f5bb6739dc44d7602d7393de8b50769c8b59cd Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 25 Mar 2026 17:02:38 +0100 Subject: [PATCH 02/10] docs: nest MCP client pages under mcp/ directory and refine Claude Desktop content Move mcp.md, chatgpt.md, and claude-desktop.md into a mcp/ subdirectory so client-specific pages appear as children of the MCP server page. Fix relative image paths after the move. Refine Claude Desktop troubleshooting based on related issues (apify/apify-mcp-server#551, #560, #592, #599): - Expand connector directory warning (affects all OSes) - Add mcp-remote config with --header auth syntax - Add "Unable to connect" section with uninstall/reinstall fix - Note that server may communicate successfully while Claude shows error Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integrations/ai/{ => mcp}/chatgpt.md | 4 ++-- .../ai/{ => mcp}/claude-desktop.md | 19 ++++++++++++++----- .../integrations/ai/{mcp.md => mcp/index.md} | 2 +- 3 files changed, 17 insertions(+), 8 deletions(-) rename sources/platform/integrations/ai/{ => mcp}/chatgpt.md (97%) rename sources/platform/integrations/ai/{ => mcp}/claude-desktop.md (84%) rename sources/platform/integrations/ai/{mcp.md => mcp/index.md} (99%) diff --git a/sources/platform/integrations/ai/chatgpt.md b/sources/platform/integrations/ai/mcp/chatgpt.md similarity index 97% rename from sources/platform/integrations/ai/chatgpt.md rename to sources/platform/integrations/ai/mcp/chatgpt.md index 8b5259baa0..062c61534c 100644 --- a/sources/platform/integrations/ai/chatgpt.md +++ b/sources/platform/integrations/ai/mcp/chatgpt.md @@ -40,7 +40,7 @@ Before connecting ChatGPT to Apify, you'll need: 3. Select **Create** to proceed to the authentication page. You’ll be redirected to the Apify website to authorize ChatGPT to access your Apify account. -![ChatGPT Create connection](../images/chatgpt-connector.png) +![ChatGPT Create connection](../../images/chatgpt-connector.png) Once authorized, you'll return to ChatGPT and see a success message with a list of tools available from the Apify MCP server. @@ -63,7 +63,7 @@ Once your connector is ready: You'll need to grant permission for each Apify tool when it's used for the first time. You should see ChatGPT calling Apify tools - such as the [RAG Web Browser](https://apify.com/apify/rag-web-browser) - to gather information. -![ChatGPT Apify tools](../images/chatgpt-with-rag-web-browser.png) +![ChatGPT Apify tools](../../images/chatgpt-with-rag-web-browser.png) ## Limitations diff --git a/sources/platform/integrations/ai/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md similarity index 84% rename from sources/platform/integrations/ai/claude-desktop.md rename to sources/platform/integrations/ai/mcp/claude-desktop.md index 2039dde52a..4014247460 100644 --- a/sources/platform/integrations/ai/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -27,7 +27,7 @@ Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/a :::caution Connector directory -If you found Apify through the Claude Desktop connector directory, the automatic install may fail silently or show an "Unable to connect to extension server" error. Use the `.mcpb` file above or the [manual configuration](#remote-server-manual-configuration) below instead. +If you found Apify through the Claude Desktop connector directory, the automatic install may fail silently or show an "Unable to connect to extension server" error. This is a known issue across macOS, Windows, and Linux. Try uninstalling and reinstalling the extension first. If that doesn't help, use the `.mcpb` file above or the [manual configuration](#remote-server-manual-configuration) instead. ::: @@ -84,13 +84,19 @@ If your version of Claude Desktop does not support the `url` field, use the `mcp "mcpServers": { "apify": { "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.apify.com/sse"] + "args": [ + "-y", + "mcp-remote", + "https://mcp.apify.com/sse", + "--header", + "Authorization: Bearer " + ] } } } ``` -This requires Node.js version 18 or higher. +Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. This requires Node.js version 18 or higher. ::: @@ -142,12 +148,15 @@ The local stdio server does not support output schema inference for structured A - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - **Validate JSON syntax.** Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. -### "Unable to connect" error +### "Unable to connect to extension server" error +This error commonly appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. + +- **Uninstall and reinstall the extension.** In Claude Desktop, disable the Apify extension, remove it, then add it again. +- **Switch to manual configuration.** If reinstalling doesn't help, use the [remote server](#remote-server-manual-configuration) or [local stdio](#local-stdio-server) setup instead of the connector directory. - **Verify the server URL.** For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. - **Check your network.** Ensure your firewall or VPN is not blocking the connection. - **For local stdio setup:** Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. -- **Try the remote server.** If the local server fails, switch to the [remote server configuration](#remote-server-manual-configuration) to rule out local environment issues. ### Corrupted npx cache diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp/index.md similarity index 99% rename from sources/platform/integrations/ai/mcp.md rename to sources/platform/integrations/ai/mcp/index.md index 50113c5a55..e9637bd533 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -17,7 +17,7 @@ using [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-star discover and run Actors from [Apify Store](https://apify.com/store), access storages and results, and enables AI coding assistants to access Apify documentation and tutorials. -![Apify MCP server](../../images/apify_mcp_server.png) +![Apify MCP server](../../../images/apify_mcp_server.png) ## Prerequisites From f0485ae80dc6f5948cf1992c5317e6d4c26eb884 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 25 Mar 2026 17:28:05 +0100 Subject: [PATCH 03/10] docs: refine Claude Desktop page after style review - Expand front matter description to 140-160 char range - Fix gerund heading (Tools not loading -> Tools fail to load) - Add intro text to troubleshooting subsections - Restore bold lead-ins to match codebase convention - Add anchor links to setup method list - Shorten connector directory admonition with link to troubleshooting - Remove mcp-remote section Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integrations/ai/mcp/claude-desktop.md | 52 ++++++------------- 1 file changed, 17 insertions(+), 35 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index 4014247460..ee90746fbc 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -1,7 +1,7 @@ --- title: Claude Desktop integration sidebar_label: Claude Desktop -description: Set up the Apify MCP server in Claude Desktop with remote or local configuration, and troubleshoot common connection issues. +description: Learn how to set up the Apify MCP server in Claude Desktop with remote or local configuration, and troubleshoot common connection issues. sidebar_position: 1.5 slug: /integrations/claude-desktop --- @@ -19,15 +19,19 @@ Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/ ## Connect to Apify -Choose one of the following methods, from simplest to most flexible. +Choose one of the following methods, from simplest to most flexible: + +- [One-click installation](#one-click-installation-recommended) with the `.mcpb` file (recommended) +- [Remote server configuration](#remote-server-manual-configuration) (no local dependencies) +- [Local stdio server](#local-stdio-server) (development, testing, or offline access) ### One-click installation (recommended) Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. -:::caution Connector directory +:::note Direct install from Claude Desktop may fail -If you found Apify through the Claude Desktop connector directory, the automatic install may fail silently or show an "Unable to connect to extension server" error. This is a known issue across macOS, Windows, and Linux. Try uninstalling and reinstalling the extension first. If that doesn't help, use the `.mcpb` file above or the [manual configuration](#remote-server-manual-configuration) instead. +Installing Apify directly from Claude Desktop's connector list may fail silently or show connection errors. Use the `.mcpb` file above or [manual configuration](#remote-server-manual-configuration) instead. See [troubleshooting](#unable-to-connect-to-extension-server-error) for details. ::: @@ -75,31 +79,6 @@ Replace `` with your API token from the [Integrations section](http -:::note Older Claude Desktop versions - -If your version of Claude Desktop does not support the `url` field, use the `mcp-remote` bridge package: - -```json -{ - "mcpServers": { - "apify": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://mcp.apify.com/sse", - "--header", - "Authorization: Bearer " - ] - } - } -} -``` - -Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. This requires Node.js version 18 or higher. - -::: - ### Local stdio server Run the MCP server locally for development, testing, or when you need offline access. This method requires Node.js. @@ -134,13 +113,14 @@ The local stdio server does not support output schema inference for structured A 1. Restart Claude Desktop after saving configuration changes. 1. Open a new conversation. -1. Look for the hammer icon in the chat input area - this indicates MCP tools are available. -1. Click the hammer icon to confirm Apify tools appear in the list. +1. Check that Apify tools are available in the tools list. 1. Test with a prompt like: "Search for web scraping Actors on Apify." ## Troubleshooting -### Tools not loading +### Tools fail to load + +The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. - **Restart Claude Desktop.** Configuration changes only take effect after a restart. - **Check the config file location.** Verify you edited the correct file: @@ -178,6 +158,8 @@ After clearing the cache, restart Claude Desktop to re-download the server packa ### Authentication errors +Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. + - **Check your API token.** Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. - **For local stdio setup:** Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. - **For remote OAuth:** Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. @@ -194,9 +176,9 @@ Look for files with `mcp` in the name for server-specific error messages. ## Known limitations -- **Connector directory:** The Claude Desktop connector directory may not install Apify correctly. Use the [`.mcpb` file](#one-click-installation-recommended) or [manual configuration](#remote-server-manual-configuration) instead. -- **Cowork mode:** Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server. -- **Transport inconsistencies:** Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. +- The Claude Desktop connector directory may not install Apify correctly. Use the [`.mcpb` file](#one-click-installation-recommended) or [manual configuration](#remote-server-manual-configuration) instead. +- Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server. +- Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. ## Next steps From 516955475b90474eae8bf08f6520ab30b6ed320a Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 26 Mar 2026 16:22:09 +0100 Subject: [PATCH 04/10] claude review --- .../integrations/ai/mcp/claude-desktop.md | 38 ++++++++++--------- sources/platform/integrations/ai/mcp/index.md | 4 +- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index ee90746fbc..54a3fe9a5d 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -1,7 +1,7 @@ --- title: Claude Desktop integration sidebar_label: Claude Desktop -description: Learn how to set up the Apify MCP server in Claude Desktop with remote or local configuration, and troubleshoot common connection issues. +description: Set up the Apify MCP server in Claude Desktop using one-click install, remote server, or local stdio, and troubleshoot common issues. sidebar_position: 1.5 slug: /integrations/claude-desktop --- @@ -27,7 +27,7 @@ Choose one of the following methods, from simplest to most flexible: ### One-click installation (recommended) -Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. +Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. :::note Direct install from Claude Desktop may fail @@ -118,27 +118,29 @@ The local stdio server does not support output schema inference for structured A ## Troubleshooting -### Tools fail to load + + +#### Tools fail to load The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. -- **Restart Claude Desktop.** Configuration changes only take effect after a restart. -- **Check the config file location.** Verify you edited the correct file: +- _Restart Claude Desktop._ Configuration changes only take effect after a restart. +- _Check the config file location._ Verify you edited the correct file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` -- **Validate JSON syntax.** Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. +- _Validate JSON syntax._ Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. -### "Unable to connect to extension server" error +#### "Unable to connect to extension server" error This error commonly appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. -- **Uninstall and reinstall the extension.** In Claude Desktop, disable the Apify extension, remove it, then add it again. -- **Switch to manual configuration.** If reinstalling doesn't help, use the [remote server](#remote-server-manual-configuration) or [local stdio](#local-stdio-server) setup instead of the connector directory. -- **Verify the server URL.** For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. -- **Check your network.** Ensure your firewall or VPN is not blocking the connection. -- **For local stdio setup:** Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. +- _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. +- _Switch to manual configuration._ If reinstalling doesn't help, use the [remote server](#remote-server-manual-configuration) or [local stdio](#local-stdio-server) setup instead of the connector directory. +- _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. +- _Check your network._ Ensure your firewall or VPN is not blocking the connection. +- _For local stdio setup:_ Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. -### Corrupted npx cache +#### Corrupted npx cache A stale or corrupted npx cache can prevent the local server from starting. Clear the cache and retry: @@ -156,15 +158,15 @@ A stale or corrupted npx cache can prevent the local server from starting. Clear After clearing the cache, restart Claude Desktop to re-download the server package. -### Authentication errors +#### Authentication errors Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. -- **Check your API token.** Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. -- **For local stdio setup:** Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. -- **For remote OAuth:** Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. +- _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. +- _For local stdio setup:_ Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. +- _For remote OAuth:_ Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. -### Check Claude Desktop logs +#### Check Claude Desktop logs If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors: diff --git a/sources/platform/integrations/ai/mcp/index.md b/sources/platform/integrations/ai/mcp/index.md index e9637bd533..88f114a1a1 100644 --- a/sources/platform/integrations/ai/mcp/index.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -434,7 +434,9 @@ documentation queries. If you exceed this limit, you'll receive a `429` response ## Troubleshooting :::tip Claude Desktop issues -For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting). + +For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting). + ::: ##### Authentication errors From 3f26ff1a97c2683be59e72a7e09cb6803e898f08 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 1 Apr 2026 19:15:02 +0200 Subject: [PATCH 05/10] review --- .../integrations/ai/mcp/claude-desktop.md | 115 +++++++----------- sources/platform/integrations/ai/mcp/index.md | 20 ++- 2 files changed, 53 insertions(+), 82 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index 54a3fe9a5d..021aeafa5f 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -1,7 +1,7 @@ --- title: Claude Desktop integration sidebar_label: Claude Desktop -description: Set up the Apify MCP server in Claude Desktop using one-click install, remote server, or local stdio, and troubleshoot common issues. +description: Set up the Apify MCP server in Claude Desktop using the remote server or one-click connector install, and troubleshoot common issues. sidebar_position: 1.5 slug: /integrations/claude-desktop --- @@ -9,39 +9,27 @@ slug: /integrations/claude-desktop import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. +Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/platform/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. ## Prerequisites - An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations) - [Claude Desktop](https://claude.ai/download) installed -- [Node.js](https://nodejs.org/) version 18 or higher (only required for [local stdio setup](#local-stdio-server)) ## Connect to Apify -Choose one of the following methods, from simplest to most flexible: +Choose one of the following methods: -- [One-click installation](#one-click-installation-recommended) with the `.mcpb` file (recommended) -- [Remote server configuration](#remote-server-manual-configuration) (no local dependencies) -- [Local stdio server](#local-stdio-server) (development, testing, or offline access) +- [Remote server](#remote-server-recommended) - recommended, automatic updates, OAuth support, no local dependencies +- [One-click installation](#one-click-installation) via the connector directory -### One-click installation (recommended) +### Remote server (recommended) -Download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb). Claude Desktop automatically registers the Apify MCP server and prompts you to approve the connection. - -:::note Direct install from Claude Desktop may fail - -Installing Apify directly from Claude Desktop's connector list may fail silently or show connection errors. Use the `.mcpb` file above or [manual configuration](#remote-server-manual-configuration) instead. See [troubleshooting](#unable-to-connect-to-extension-server-error) for details. - -::: - -### Remote server (manual configuration) - -The remote server at `https://mcp.apify.com` is the simplest manual setup - no local dependencies required. +The remote server at `https://mcp.apify.com` is the recommended way to connect. It provides automatic updates, OAuth authentication, and requires no local dependencies or API token management. 1. Open Claude Desktop. 1. Go to **Settings** > **Developer** > **Edit Config**. -1. Add the Apify MCP server configuration: +1. Edit the configuration file to add the Apify MCP server: @@ -74,40 +62,20 @@ On first connection, your browser opens to sign in to Apify and authorize the co } ``` -Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. +Replace `` with your API token obtained from the [Apify Console](https://console.apify.com/account#/integrations). -### Local stdio server +### One-click installation -Run the MCP server locally for development, testing, or when you need offline access. This method requires Node.js. +You can install the Apify MCP server directly from the Claude Desktop connector directory: 1. Open Claude Desktop. -1. Go to **Settings** > **Developer** > **Edit Config**. -1. Add the following configuration: - -```json -{ - "mcpServers": { - "actors-mcp-server": { - "command": "npx", - "args": ["-y", "@apify/actors-mcp-server"], - "env": { - "APIFY_TOKEN": "" - } - } - } -} -``` +1. Go to **Settings** > **Connectors** > **Browse connectors**. +1. Search for Apify and install the connector. -Replace `` with your API token from the [Integrations section](https://console.apify.com/account#/integrations) in Apify Console. - -:::info Output schema inference - -The local stdio server does not support output schema inference for structured Actor results. Use the [remote server](#remote-server-manual-configuration) to get automatic output schemas with field-level type information. - -::: +Alternatively, you can download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. ## Verify the connection @@ -120,6 +88,21 @@ The local stdio server does not support output schema inference for structured A +If the steps below don't resolve your issue, [submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). + + +#### "Unable to connect to extension server" error + +This is the most common issue. It typically appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. + +1. _Consider switching to the [remote server](#remote-server-recommended) setup._ Manual configuration with the remote server is the most reliable option. +1. _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. +1. _Clear the npx cache._ A stale cache can cause connection failures. Follow the steps in [Corrupted npx cache](#corrupted-npx-cache). +1. _Check the [Claude Desktop logs](#check-claude-desktop-logs)_ for specific error messages. +1. _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. +1. _Check your network._ Ensure your firewall or VPN is not blocking the connection. +1. _Still not working?_ [Submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). + #### Tools fail to load The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. @@ -130,40 +113,33 @@ The MCP server shows as connected but Apify tools don't appear in the tools list - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - _Validate JSON syntax._ Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. -#### "Unable to connect to extension server" error - -This error commonly appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. - -- _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. -- _Switch to manual configuration._ If reinstalling doesn't help, use the [remote server](#remote-server-manual-configuration) or [local stdio](#local-stdio-server) setup instead of the connector directory. -- _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. -- _Check your network._ Ensure your firewall or VPN is not blocking the connection. -- _For local stdio setup:_ Confirm Node.js version 18 or higher is installed by running `node -v` in your terminal. - #### Corrupted npx cache -A stale or corrupted npx cache can prevent the local server from starting. Clear the cache and retry: +A stale or corrupted npx cache can prevent the server from starting. Clear the cache and retry: + +1. Clear the npx cache: -- macOS and Linux: + - macOS and Linux: - ```bash - rm -rf ~/.npm/_npx - ``` + ```bash + rm -rf ~/.npm/_npx + ``` -- Windows: + - Windows: - ```bash - rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx - ``` + ```bash + rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx + ``` -After clearing the cache, restart Claude Desktop to re-download the server package. +1. Restart Claude Desktop to re-download the server package. +1. Check the [Claude Desktop logs](#check-claude-desktop-logs) for errors. +1. If the issue persists, switch to the [remote server](#remote-server-recommended) setup, which doesn't rely on local packages. #### Authentication errors Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. - _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. -- _For local stdio setup:_ Ensure the `APIFY_TOKEN` environment variable is set correctly in your config file. - _For remote OAuth:_ Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. #### Check Claude Desktop logs @@ -178,12 +154,11 @@ Look for files with `mcp` in the name for server-specific error messages. ## Known limitations -- The Claude Desktop connector directory may not install Apify correctly. Use the [`.mcpb` file](#one-click-installation-recommended) or [manual configuration](#remote-server-manual-configuration) instead. -- Multi-agent cowork mode may not pass MCP tool results between agents reliably when using the local stdio server. - Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. +- If the connector directory installation fails, use the [remote server](#remote-server-recommended) at `https://mcp.apify.com` instead. ## Next steps -- [Apify MCP server](/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits +- [Apify MCP server](/platform/integrations/mcp) - Explore tool selection, available tools, telemetry, and rate limits - [Apify MCP server configurator](https://mcp.apify.com) - Select tools visually and copy configuration - [Apify MCP server on GitHub](https://github.com/apify/apify-mcp-server) - Report bugs and suggest features diff --git a/sources/platform/integrations/ai/mcp/index.md b/sources/platform/integrations/ai/mcp/index.md index 613694e546..7ac10c0fac 100644 --- a/sources/platform/integrations/ai/mcp/index.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -1,6 +1,6 @@ --- title: Apify MCP server -sidebar_label: MCP +sidebar_label: MCP server description: Learn how to use the Apify MCP server to integrate Apify's library of Actors into your AI agents or large language model-based applications. sidebar_position: 1 slug: /integrations/mcp @@ -210,33 +210,29 @@ VS Code supports MCP through GitHub Copilot's agent mode (requires Copilot subsc :::tip One-click installation -Download and run the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) for one-click installation. +Install the Apify connector directly from Claude Desktop: go to **Settings** > **Connectors** > **Browse connector** and search for Apify. ::: To manually configure Apify's MCP server for Claude Desktop: 1. Open Claude Desktop settings. -1. Navigate to the **Developer** section. +1. Go to **Settings** > **Developer** > **Edit Config**. 1. Add the following to the configuration file: ```json { "mcpServers": { - "actors-mcp-server": { - "command": "npx", - "args": ["-y", "@apify/actors-mcp-server"], - "env": { - "APIFY_TOKEN": "" - } + "apify": { + "url": "https://mcp.apify.com" } } } ``` -Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). +On first connection, your browser opens to sign in to Apify and authorize the connection. -For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/integrations/claude-desktop). +For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/platform/integrations/claude-desktop). @@ -403,7 +399,7 @@ documentation queries. If you exceed this limit, you'll receive a `429` response :::tip Claude Desktop issues -For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/integrations/claude-desktop#troubleshooting). +For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/platform/integrations/claude-desktop#troubleshooting). ::: From deffc6f0a0ffd92e21af50da72e57b1ef877fd60 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 1 Apr 2026 19:21:55 +0200 Subject: [PATCH 06/10] review final --- sources/platform/integrations/ai/mcp/chatgpt.md | 12 ++++++------ .../platform/integrations/ai/mcp/claude-desktop.md | 13 ++++++++----- sources/platform/integrations/ai/mcp/index.md | 6 +++--- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/chatgpt.md b/sources/platform/integrations/ai/mcp/chatgpt.md index ac1ae110a9..d86ed8246b 100644 --- a/sources/platform/integrations/ai/mcp/chatgpt.md +++ b/sources/platform/integrations/ai/mcp/chatgpt.md @@ -31,17 +31,17 @@ Before connecting ChatGPT to Apify, you'll need: 1. In ChatGPT, go to **Settings > Apps & Connectors > Create**. If you don't see the **Create** button, enable Developer mode or reload the page. -2. Fill in the following fields: +1. Fill in the following fields: - - **Name** – a user-facing title, e.g., `apify-mcp` - - **Description** – a short description of what the connector does - - **MCP Server URL** – choose one of the following: + - **Name** - a user-facing title, e.g., `apify-mcp` + - **Description** - a short description of what the connector does + - **MCP Server URL** - choose one of the following: - `https://mcp.apify.com` - use the default set of Apify tools - `https://mcp.apify.com?tools=actors,docs,mtrunkat/url-list-download-html` - use specific tools - Refer to [mcp.apify.com](https://mcp.apify.com) for details - - **Authentication** – OAuth, you don’t need to provide a client ID or secret. + - **Authentication** - OAuth, you don’t need to provide a client ID or secret. -3. Select **Create** to proceed to the authentication page. +1. Select **Create** to proceed to the authentication page. You’ll be redirected to the Apify website to authorize ChatGPT to access your Apify account. ![ChatGPT Create connection](../../images/chatgpt-connector.png) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index 021aeafa5f..393fc976be 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -8,9 +8,12 @@ slug: /integrations/claude-desktop import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/platform/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. + + ## Prerequisites - An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations) @@ -62,7 +65,7 @@ On first connection, your browser opens to sign in to Apify and authorize the co } ``` -Replace `` with your API token obtained from the [Apify Console](https://console.apify.com/account#/integrations). +Replace `` with your API token obtained from [Apify Console](https://console.apify.com/account#/integrations). @@ -75,7 +78,7 @@ You can install the Apify MCP server directly from the Claude Desktop connector 1. Go to **Settings** > **Connectors** > **Browse connectors**. 1. Search for Apify and install the connector. -Alternatively, you can download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/apify-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. +Alternatively, you can download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. ## Verify the connection @@ -98,7 +101,7 @@ This is the most common issue. It typically appears when installing from the Cla 1. _Consider switching to the [remote server](#remote-server-recommended) setup._ Manual configuration with the remote server is the most reliable option. 1. _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. 1. _Clear the npx cache._ A stale cache can cause connection failures. Follow the steps in [Corrupted npx cache](#corrupted-npx-cache). -1. _Check the [Claude Desktop logs](#check-claude-desktop-logs)_ for specific error messages. +1. _Check the [Claude Desktop logs](#claude-desktop-logs)_ for specific error messages. 1. _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. 1. _Check your network._ Ensure your firewall or VPN is not blocking the connection. 1. _Still not working?_ [Submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). @@ -132,7 +135,7 @@ A stale or corrupted npx cache can prevent the server from starting. Clear the c ``` 1. Restart Claude Desktop to re-download the server package. -1. Check the [Claude Desktop logs](#check-claude-desktop-logs) for errors. +1. Check the [Claude Desktop logs](#claude-desktop-logs) for errors. 1. If the issue persists, switch to the [remote server](#remote-server-recommended) setup, which doesn't rely on local packages. #### Authentication errors @@ -142,7 +145,7 @@ Authentication errors occur when the MCP server can't verify your identity. You - _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. - _For remote OAuth:_ Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. -#### Check Claude Desktop logs +#### Claude Desktop logs If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors: diff --git a/sources/platform/integrations/ai/mcp/index.md b/sources/platform/integrations/ai/mcp/index.md index 7ac10c0fac..bb2c23078a 100644 --- a/sources/platform/integrations/ai/mcp/index.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -210,7 +210,7 @@ VS Code supports MCP through GitHub Copilot's agent mode (requires Copilot subsc :::tip One-click installation -Install the Apify connector directly from Claude Desktop: go to **Settings** > **Connectors** > **Browse connector** and search for Apify. +Install the Apify connector directly from Claude Desktop: go to **Settings** > **Connectors** > **Browse connectors** and search for Apify. ::: @@ -399,7 +399,7 @@ documentation queries. If you exceed this limit, you'll receive a `429` response :::tip Claude Desktop issues -For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/platform/integrations/claude-desktop#troubleshooting). +For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see [Claude Desktop troubleshooting](/platform/integrations/claude-desktop#troubleshooting). ::: @@ -426,7 +426,7 @@ If you find this project useful, please star it on [GitHub](https://github.com/a To learn more about MCP and Apify integration: -- [Model Context Protocol specification](https://modelcontextprotocol.io) - Learn about the open standard on the official MCP website – understanding the protocol can help you build custom agents. +- [Model Context Protocol specification](https://modelcontextprotocol.io) - Learn about the open standard on the official MCP website - understanding the protocol can help you build custom agents. - [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/) - Learn how to expose over thousands of Apify Actors to AI agents with Claude and LangGraph, and configure MCP clients and servers. - [Video tutorial](https://www.youtube.com/watch?v=BKu8H91uCTg) - Integrate thousands of Apify Actors and Agents with Claude. - [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) - A specialized client Actor that you can run to simulate an AI agent in your browser. Useful for testing your setup with a chat UI. From 85cc4032240bcb942ba793eed9caf70dd38e7ba8 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 2 Apr 2026 13:19:05 +0200 Subject: [PATCH 07/10] docs: address Jiri's review - simplify setup, scope troubleshooting - Replace explicit UI paths with link to Claude support article - Make remote server advantages prominent (auto updates, OAuth, no deps) - Scope troubleshooting to one-click installation only - Remove JSON config blocks and Tabs imports (no longer needed) - Simplify "Tools fail to load" section - Add support contact info early in prerequisites Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integrations/ai/mcp/claude-desktop.md | 67 +++++-------------- 1 file changed, 15 insertions(+), 52 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index 393fc976be..ce6b2f7ee6 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -6,8 +6,6 @@ sidebar_position: 1.5 slug: /integrations/claude-desktop --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/platform/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. @@ -28,57 +26,21 @@ Choose one of the following methods: ### Remote server (recommended) -The remote server at `https://mcp.apify.com` is the recommended way to connect. It provides automatic updates, OAuth authentication, and requires no local dependencies or API token management. +The remote server at `https://mcp.apify.com` is the recommended way to connect. Key advantages: -1. Open Claude Desktop. -1. Go to **Settings** > **Developer** > **Edit Config**. -1. Edit the configuration file to add the Apify MCP server: +- **Automatic updates** - always runs the latest version of the Apify MCP server +- **OAuth authentication** - secure sign-in through your browser, no API token needed +- **No local dependencies** - nothing to install or maintain on your machine - - +To set up the remote server, [add a custom connector](https://support.claude.com/en/articles/11175166) in Claude Desktop and use `https://mcp.apify.com` as the server URL. -```json -{ - "mcpServers": { - "apify": { - "url": "https://mcp.apify.com" - } - } -} -``` - -On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure. - - - - -```json -{ - "mcpServers": { - "apify": { - "url": "https://mcp.apify.com", - "headers": { - "Authorization": "Bearer " - } - } - } -} -``` - -Replace `` with your API token obtained from [Apify Console](https://console.apify.com/account#/integrations). - - - +On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure - you don't need to manage or paste an API token. ### One-click installation -You can install the Apify MCP server directly from the Claude Desktop connector directory: - -1. Open Claude Desktop. -1. Go to **Settings** > **Connectors** > **Browse connectors**. -1. Search for Apify and install the connector. +You can install the Apify MCP server directly from the [Claude Desktop connector directory](https://support.claude.com/en/articles/11175166). Search for "Apify" and install the connector. -Alternatively, you can download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. +Alternatively, download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. ## Verify the connection @@ -91,6 +53,10 @@ Alternatively, you can download and open the [Apify MCP server `.mcpb` file](htt +:::note One-click installation only +The troubleshooting steps below apply to the [one-click installation](#one-click-installation) method. The remote server runs entirely on Apify's infrastructure, so there are no local logs or configuration to debug. If you experience issues with the [remote server](#remote-server-recommended), contact [Apify support](https://apify.com/contact). +::: + If the steps below don't resolve your issue, [submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). @@ -98,11 +64,10 @@ If the steps below don't resolve your issue, [submit a GitHub issue](https://git This is the most common issue. It typically appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. -1. _Consider switching to the [remote server](#remote-server-recommended) setup._ Manual configuration with the remote server is the most reliable option. +1. _Consider switching to the [remote server](#remote-server-recommended) setup._ The remote server is the most reliable option. 1. _Uninstall and reinstall the extension._ In Claude Desktop, disable the Apify extension, remove it, then add it again. 1. _Clear the npx cache._ A stale cache can cause connection failures. Follow the steps in [Corrupted npx cache](#corrupted-npx-cache). 1. _Check the [Claude Desktop logs](#claude-desktop-logs)_ for specific error messages. -1. _Verify the server URL._ For remote setup, use exactly `https://mcp.apify.com` with no trailing slash. 1. _Check your network._ Ensure your firewall or VPN is not blocking the connection. 1. _Still not working?_ [Submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). @@ -111,10 +76,8 @@ This is the most common issue. It typically appears when installing from the Cla The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. - _Restart Claude Desktop._ Configuration changes only take effect after a restart. -- _Check the config file location._ Verify you edited the correct file: - - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - - Windows: `%APPDATA%\Claude\claude_desktop_config.json` -- _Validate JSON syntax._ Ensure there are no trailing commas, missing quotes, or mismatched brackets. Paste your config into a JSON validator if needed. +- _Reinstall the connector._ Remove the Apify connector and add it again. +- _Switch to the [remote server](#remote-server-recommended)._ The remote server is the most reliable connection method. #### Corrupted npx cache From b6420d7e80c7e24df3434e006a591530cc6028e4 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 2 Apr 2026 14:02:45 +0200 Subject: [PATCH 08/10] docs: update prerequisites and troubleshooting instructions for Claude Desktop integration --- sources/platform/integrations/ai/mcp/claude-desktop.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index ce6b2f7ee6..78cadbc978 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -14,7 +14,7 @@ Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/ ## Prerequisites -- An [Apify account](https://console.apify.com/sign-up) with an [API token](https://console.apify.com/account#/integrations) +- An [Apify account](https://console.apify.com/sign-up) - [Claude Desktop](https://claude.ai/download) installed ## Connect to Apify @@ -59,7 +59,6 @@ The troubleshooting steps below apply to the [one-click installation](#one-click If the steps below don't resolve your issue, [submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). - #### "Unable to connect to extension server" error This is the most common issue. It typically appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. @@ -106,7 +105,7 @@ A stale or corrupted npx cache can prevent the server from starting. Clear the c Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. - _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. -- _For remote OAuth:_ Remove and re-add the Apify MCP server in Claude Desktop to re-authorize. +- _Re-authorize the connection._ Remove and re-add the Apify connector in Claude Desktop. #### Claude Desktop logs From ea2630cab429b711a3a6e7a7a549d457337d60b7 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 2 Apr 2026 23:43:13 +0200 Subject: [PATCH 09/10] review --- .../integrations/ai/mcp/claude-desktop.md | 95 ++++++++++--------- 1 file changed, 50 insertions(+), 45 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index 78cadbc978..a8cd3a7ecf 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -1,11 +1,13 @@ --- title: Claude Desktop integration sidebar_label: Claude Desktop -description: Set up the Apify MCP server in Claude Desktop using the remote server or one-click connector install, and troubleshoot common issues. -sidebar_position: 1.5 +description: Learn how to set up the Apify MCP server in Claude Desktop using the remote server or one-click connector install, and troubleshoot common issues. +sidebar_position: 2 slug: /integrations/claude-desktop --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/platform/integrations/mcp) to give your conversations access to thousands of Actors from [Apify Store](https://apify.com/store). Once connected, Claude can search for, run, and retrieve results from Actors directly in your chat. @@ -22,15 +24,15 @@ Connect [Claude Desktop](https://claude.ai/download) to the [Apify MCP server](/ Choose one of the following methods: - [Remote server](#remote-server-recommended) - recommended, automatic updates, OAuth support, no local dependencies -- [One-click installation](#one-click-installation) via the connector directory +- [One-click installation](#one-click-installation) - install from the connector directory ### Remote server (recommended) The remote server at `https://mcp.apify.com` is the recommended way to connect. Key advantages: -- **Automatic updates** - always runs the latest version of the Apify MCP server -- **OAuth authentication** - secure sign-in through your browser, no API token needed -- **No local dependencies** - nothing to install or maintain on your machine +- Automatic updates - always runs the latest version of the Apify MCP server +- OAuth authentication - secure sign-in through your browser, no API token needed +- No local dependencies - nothing to install or maintain on your machine To set up the remote server, [add a custom connector](https://support.claude.com/en/articles/11175166) in Claude Desktop and use `https://mcp.apify.com` as the server URL. @@ -38,7 +40,7 @@ On first connection, your browser opens to sign in to Apify and authorize the co ### One-click installation -You can install the Apify MCP server directly from the [Claude Desktop connector directory](https://support.claude.com/en/articles/11175166). Search for "Apify" and install the connector. +Search for "Apify" in the [Claude Desktop connector directory](https://support.claude.com/en/articles/11175166) and install the connector. Alternatively, download and open the [Apify MCP server `.mcpb` file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) to register the connector automatically. @@ -53,12 +55,35 @@ Alternatively, download and open the [Apify MCP server `.mcpb` file](https://git -:::note One-click installation only -The troubleshooting steps below apply to the [one-click installation](#one-click-installation) method. The remote server runs entirely on Apify's infrastructure, so there are no local logs or configuration to debug. If you experience issues with the [remote server](#remote-server-recommended), contact [Apify support](https://apify.com/contact). -::: - If the steps below don't resolve your issue, [submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). +#### Tools fail to load + +The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. + +- _Restart Claude Desktop._ Configuration changes only take effect after a restart. +- _Reinstall the connector._ Remove the Apify connector and add it again. + +#### Authentication errors + +Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. + +- _Re-authorize the connection._ Remove and re-add the Apify connector in Claude Desktop to trigger a new OAuth flow. + +#### Claude Desktop logs + +Check the Claude Desktop logs for MCP-related errors: + +- macOS: `~/Library/Logs/Claude/` +- Linux: `~/.config/Claude/logs/` +- Windows: `%APPDATA%\Claude\logs\` + +Look for files with `mcp` in the name for server-specific error messages. + +### One-click installation issues + +The following troubleshooting steps apply specifically to the [one-click installation](#one-click-installation) method. The remote server runs entirely on Apify's infrastructure, so there are no local logs or configuration to debug. If you experience issues with the [remote server](#remote-server-recommended), contact [Apify support](https://apify.com/contact). + #### "Unable to connect to extension server" error This is the most common issue. It typically appears when installing from the Claude Desktop connector directory. In some cases, the MCP server starts and communicates correctly, but Claude Desktop still shows the error. @@ -70,53 +95,33 @@ This is the most common issue. It typically appears when installing from the Cla 1. _Check your network._ Ensure your firewall or VPN is not blocking the connection. 1. _Still not working?_ [Submit a GitHub issue](https://github.com/apify/apify-mcp-server/issues) or contact [Apify support](https://apify.com/contact). -#### Tools fail to load - -The MCP server shows as connected but Apify tools don't appear in the tools list, or Claude doesn't recognize any Apify tools in conversation. - -- _Restart Claude Desktop._ Configuration changes only take effect after a restart. -- _Reinstall the connector._ Remove the Apify connector and add it again. -- _Switch to the [remote server](#remote-server-recommended)._ The remote server is the most reliable connection method. - #### Corrupted npx cache A stale or corrupted npx cache can prevent the server from starting. Clear the cache and retry: -1. Clear the npx cache: + + + +```bash +rm -rf ~/.npm/_npx +``` - - macOS and Linux: + + - ```bash - rm -rf ~/.npm/_npx - ``` +```text +rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx +``` - - Windows: + + - ```bash - rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx - ``` +After clearing the cache: 1. Restart Claude Desktop to re-download the server package. 1. Check the [Claude Desktop logs](#claude-desktop-logs) for errors. 1. If the issue persists, switch to the [remote server](#remote-server-recommended) setup, which doesn't rely on local packages. -#### Authentication errors - -Authentication errors occur when the MCP server can't verify your identity. You may see "Unauthorized" or "Invalid token" messages, or Actor runs may fail silently. - -- _Check your API token._ Verify the token in the [Integrations section](https://console.apify.com/account#/integrations) of Apify Console. -- _Re-authorize the connection._ Remove and re-add the Apify connector in Claude Desktop. - -#### Claude Desktop logs - -If the above steps don't resolve your issue, check the Claude Desktop logs for MCP-related errors: - -- macOS: `~/Library/Logs/Claude/` -- Linux: `~/.config/Claude/logs/` -- Windows: `%APPDATA%\Claude\logs\` - -Look for files with `mcp` in the name for server-specific error messages. - ## Known limitations - Some Claude Desktop versions have inconsistent behavior with remote MCP server connections. Update to the latest version if you experience issues. From 91d76a8a123e8d240efa6945b3e9ad51959ee4ca Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 2 Apr 2026 23:52:12 +0200 Subject: [PATCH 10/10] docs: simplify setup instructions for Claude Desktop integration --- .../integrations/ai/mcp/claude-desktop.md | 2 +- sources/platform/integrations/ai/mcp/index.md | 24 ++----------------- 2 files changed, 3 insertions(+), 23 deletions(-) diff --git a/sources/platform/integrations/ai/mcp/claude-desktop.md b/sources/platform/integrations/ai/mcp/claude-desktop.md index a8cd3a7ecf..6696e3bfaf 100644 --- a/sources/platform/integrations/ai/mcp/claude-desktop.md +++ b/sources/platform/integrations/ai/mcp/claude-desktop.md @@ -36,7 +36,7 @@ The remote server at `https://mcp.apify.com` is the recommended way to connect. To set up the remote server, [add a custom connector](https://support.claude.com/en/articles/11175166) in Claude Desktop and use `https://mcp.apify.com` as the server URL. -On first connection, your browser opens to sign in to Apify and authorize the connection. This OAuth flow keeps your API token secure - you don't need to manage or paste an API token. +On first connection, your browser opens to sign in to Apify and authorize the connection. ### One-click installation diff --git a/sources/platform/integrations/ai/mcp/index.md b/sources/platform/integrations/ai/mcp/index.md index bb2c23078a..47d7823a2a 100644 --- a/sources/platform/integrations/ai/mcp/index.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -208,29 +208,9 @@ VS Code supports MCP through GitHub Copilot's agent mode (requires Copilot subsc -:::tip One-click installation - -Install the Apify connector directly from Claude Desktop: go to **Settings** > **Connectors** > **Browse connectors** and search for Apify. - -::: - -To manually configure Apify's MCP server for Claude Desktop: - -1. Open Claude Desktop settings. -1. Go to **Settings** > **Developer** > **Edit Config**. -1. Add the following to the configuration file: - -```json -{ - "mcpServers": { - "apify": { - "url": "https://mcp.apify.com" - } - } -} -``` +[Add a custom connector](https://support.claude.com/en/articles/11175166) in Claude Desktop and use `https://mcp.apify.com` as the server URL. On first connection, your browser opens to sign in to Apify and authorize the connection. -On first connection, your browser opens to sign in to Apify and authorize the connection. +You can also search for "Apify" in the connector directory and install it directly. For detailed setup options and troubleshooting, see the [Claude Desktop integration guide](/platform/integrations/claude-desktop).