ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Fix “Could Not Attach to MCP Server” in Apify

Diagnose Apify MCP connection errors by transport, then fix remote OAuth, local npx, Node.js, cache, permissions and network problems.

By the ScreenshotNeo team1 October 20266 min read

Start by identifying the transport. Apify supports a hosted remote MCP server at https://mcp.apify.com and a local stdio server launched with npx -y @apify/actors-mcp-server. A remote connection is diagnosed through client support, authorization and network access. A local connection is diagnosed through the command, Node.js/npm, the package cache and the APIFY_TOKEN environment variable.

The message “Could not attach to MCP server Apify” is a client symptom, not a root-cause diagnosis. Claude Desktop may show the related “Unable to connect to extension server” message. Follow the branch that matches your configuration.

1. Identify your Apify MCP connection

Configuration clue Transport Check first
url: "https://mcp.apify.com" Hosted remote, Streamable HTTP OAuth or bearer token, client support, firewall/VPN
command: "npx" with @apify/actors-mcp-server Local stdio Node.js, npm/npx, package cache, token and process startup

Opening mcp.apify.com in a browser does not prove that your MCP client can complete the MCP handshake or authentication flow. It only shows that a browser request reached the host.

Apify recommends remote setup for Claude Desktop. It avoids local package installation, npx cache state and most Node.js path problems. Add a custom connector using the hosted URL, then complete Apify’s browser sign-in and authorization flow.

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com"
    }
  }
}

The hosted endpoint uses Streamable HTTP. Apify documents OAuth as the normal Claude Desktop route; a bearer token can also be supplied with an Authorization: Bearer <APIFY_TOKEN> header when your MCP client supports custom headers. Keep tokens private.

Remote connection checklist

  1. Remove a broken or duplicate Apify connector.
  2. Add a custom connector for https://mcp.apify.com.
  3. Finish the Apify OAuth flow in the browser, or configure the documented bearer header.
  4. Confirm the connector’s tools are set to Always allow or Ask first, not blocked.
  5. Restart Claude Desktop, open a new conversation and check that Apify tools appear.
  6. Try a simple Actor search prompt before testing a complex workflow.

3. Fix local stdio setup

Use local stdio only when your MCP client does not support the remote URL or you specifically need a local process. The client must launch the command successfully and pass the token into that process.

{
  "mcpServers": {
    "actors-mcp-server": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server"],
      "env": {
        "APIFY_TOKEN": "YOUR_APIFY_TOKEN"
      }
    }
  }
}

Verify the local prerequisites

  • Run node --version and npx --version from a normal terminal.
  • Confirm the configured command is exactly npx and the package name is exactly @apify/actors-mcp-server.
  • Check that APIFY_TOKEN is present in the MCP process environment, not only in an interactive shell profile.
  • Do not paste the token into logs, screenshots, issues or chat messages.
  • Restart the desktop client after every configuration change.

4. Clear a stale npx cache

Apify’s Claude troubleshooting guide recommends removing the npx cache when stale package files prevent the local server from starting. This applies to the local or extension installation path, not to a fully hosted remote connection.

# macOS or Linux
rm -rf ~/.npm/_npx

# Windows Command Prompt
rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx

After clearing the cache, restart Claude Desktop so npx downloads the package again. Remove and reinstall the Apify extension or connector if your client exposes it in a connector directory.

5. Read MCP logs before changing more settings

Look for files with mcp in their name. Claude Desktop’s documented log locations are:

Operating system Log directory
macOS ~/Library/Logs/Claude/
Linux ~/.config/Claude/logs/
Windows %APPDATA%\Claude\logs\

For local stdio, the log normally distinguishes a failed process launch, missing executable, package download problem or authentication rejection. For remote MCP, ignore local npx and Node.js errors and focus on authorization, client support and network reachability.

6. Troubleshooting by symptom

Symptom Likely cause Fix
“Could not attach to MCP server Apify” immediately after adding it Wrong transport or unsupported remote MCP mode Confirm whether the config uses url or command. Try the hosted URL in a client version that supports remote MCP.
“Unable to connect to extension server” Extension install, local process or network failure Remove and reinstall the extension, clear the npx cache for local setup, inspect logs and check firewall/VPN rules.
spawn node ENOENT in Claude Cowork Node.js is available only through a version manager Install Node.js system-wide or switch Cowork to the hosted remote server. This diagnosis is specific to Cowork.
Server appears connected but no tools load Tools are blocked or the client downgraded the connector Set tools to “Always allow” or “Ask first.” Remove and re-add the connector to trigger an update; re-adding is not guaranteed to resolve every client issue.
OAuth repeatedly fails Expired or incomplete authorization session Remove and re-add the desktop connector, then complete a fresh OAuth flow.
Bearer-token setup returns unauthorized Missing, malformed or revoked token Use the Authorization: Bearer format supported by your client, create or rotate the token in Apify and keep it out of shared logs.
Local server starts on a terminal but not in the client The desktop app has a different PATH or environment Use an absolute command path where supported, install Node.js system-wide, and define APIFY_TOKEN in the MCP configuration’s env object.
Works on one network but not another Firewall, proxy or VPN restriction Try a permitted network or ask the network administrator to allow the required Apify service traffic.

7. Client-version and connector issues

Apify documents inconsistent remote-MCP behavior in some Claude Desktop versions. Claude may also silently downgrade a connector, which can prevent tools from loading. Removing and re-adding the connector may prompt an update, but it is not a guaranteed fix. Record the desktop version, transport type and relevant log line before escalating.

8. A repeatable recovery procedure

  1. Copy the current configuration somewhere safe, with tokens removed.
  2. Classify it as remote (url) or local (command).
  3. For remote: remove and re-add the connector, redo OAuth or verify the bearer header, then check tool permissions.
  4. For local: verify system-wide Node.js and npx, the package name and APIFY_TOKEN.
  5. Clear _npx only for local setup, then restart the client.
  6. Check the MCP logs and classify the failure as launch, authentication, protocol or network.
  7. Test a simple Actor search in a new conversation.
  8. If the hosted service still fails, provide Apify support or a GitHub issue with the sanitized configuration, client version, transport and log excerpt.

Or skip the browser setup

If your agent workflow only needs reliable website screenshots, ScreenshotNeo provides a direct HTTP API and an MCP server for Claude, Cursor and other MCP clients. Cookie and consent banners, newsletter popups and chat widgets are removed before capture. Bot checks, blank pages and failed loads are never billed, and each response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for the complete option list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo includes an MCP server with take_screenshot, get_page_info and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Does a browser test of mcp.apify.com prove the MCP server works?

No. The MCP client still has to launch or connect using the configured transport and complete authentication.

Should I use remote or local Apify MCP?

Use remote when your client supports the hosted URL and you want to avoid local runtime and package maintenance. Use local stdio when remote MCP is unavailable or a local process is required.

Is deleting the npx cache a fix for remote MCP?

No. It only affects local or extension installations that launch the package through npx.

Why can Claude Cowork fail while Claude Desktop works?

Cowork launches local MCP servers differently and may require a system-wide Node.js binary. A version-manager-only installation can produce spawn node ENOENT.

What information should I include in a support report?

Include the client and operating-system versions, whether the setup is remote or local, the sanitized configuration, the exact error and the relevant MCP log line. Never include an API token.

Keep reading