How to set up the Apify MCP server in Claude Code, Cursor, VS Code and Codex

Quick answer

• Coding agents (recommended): install the official Apify plugin. It sets up the hosted MCP server at https://mcp.apify.com plus Agent Skills in one step.
• By hand: add https://mcp.apify.com to your client. On first connection your browser opens so you can sign in to Apify with OAuth. You can also send an API token as Authorization: Bearer <APIFY_TOKEN>.
• Without an account: you can connect to a URL that only loads discovery and docs tools (listed below). Running Actors and reading your storage always needs sign-in or a token.
• Locally: run npx -y @apify/actors-mcp-server with APIFY_TOKEN. That needs Node.js 22 or later. Actors still run on the Apify platform.
• Then: ask in plain language, for example: "Search Apify Store for an Actor that extracts product prices from Amazon and show me its input schema and pricing before running it."

What the Apify MCP server is

The hosted server at https://mcp.apify.com is Apify's official MCP server. An agent can search Apify Store, inspect an Actor's input schema, README and pricing, run it, and read the results from the run's dataset. Connecting to the server is free. Actor runs bill to your Apify account at each Actor's price.

By default, the current server loads the actors and docs tool categories, the Web Search and Web Fetch Actors, and report-problem. call-actor returns the run status and storage IDs, not the scraped items. To read the results, use get-dataset-items with the datasetId from the run. Whenever call-actor or an Actor tool is loaded, the server also adds get-actor-run, get-dataset-items, get-key-value-store-record and abort-actor-run.

For a shorter tour of the server, see the Apify MCP Server listing. If you mainly need to search the web and turn pages into clean markdown, rather than run site-specific Actors, see how to set up the Firecrawl MCP server.

Get an Apify account (for running Actors)

You need an Apify account unless you only use the discovery and docs tools, or your agent pays through Apify's agentic payments. The free plan includes $5 of prepaid platform usage each month and does not need a credit card. Unused credits expire at the end of the billing cycle. On the free plan, once that usage is gone, access is blocked until the next monthly cycle.

Create a free account here:

If you use an API token instead of OAuth, get it from the API & Integrations section in Apify Console and treat it like a password. Keep it out of files you commit. You can revoke an OAuth connection in Apify Console > Settings > Integrations.

Option 1: install the official plugin

For Claude Code, Cursor, Codex, GitHub Copilot and VS Code, Apify recommends its plugin. One install configures the hosted MCP server and Agent Skills together. The plugin does not replace the Apify CLI. The Actor development, actorization and scraping skills call it, so install it with npm install -g apify-cli and run apify login before you use those skills.

Claude Code

/plugin marketplace add apify/apify-claude-code-plugin
/plugin install apify@apify
/reload-plugins

Then run /mcp, open plugin:apify:apify, select Enable, then select Authenticate and finish the Apify sign-in in your browser. You can also add the marketplace from the /plugins manager. Read-only tools such as searching the Store and fetching Actor details work without signing in; you need to authenticate to run Actors and access your account data. More on Claude Code: the best MCP servers for Claude Code.

Cursor

In the Cursor agent chat, run:

/add-plugin apify

You can also search for Apify under Plugins in Cursor Settings, or install it from the Cursor Marketplace. Then open Cursor Settings → Tools & MCPs, select Connect on the Apify MCP server, and complete the Apify sign-in in your browser. More: how to add an MCP server to Cursor.

Codex

In the Codex CLI, run /plugins, open the Add Marketplace tab, and enter:

apify/apify-codex-plugin

Then open the Apify Plugin tab, select Apify, and select Install plugin. The CLI opens the Apify sign-in the first time it calls a tool that needs authentication, such as running an Actor.

In the Codex app (ChatGPT desktop, with Codex selected), open Plugins in the left sidebar, select the dropdown next to +, and choose Add marketplace. Enter apify/apify-codex-plugin, add the marketplace, open the Personal tab, select Add next to Apify, then Add to Codex and Install Apify. Codex opens the Apify sign-in in your browser. More: how to add an MCP server to Codex.

VS Code and GitHub Copilot

In VS Code, open the Extensions view, search for @agentPlugins apify, install the apify entry from the Awesome Copilot marketplace, and confirm the trust prompt. When VS Code asks to authenticate the MCP server, select Allow and finish the Apify sign-in in your browser.

In the GitHub Copilot CLI, install it from the Awesome Copilot marketplace with /plugin install apify@awesome-copilot, then complete the browser sign-in. In the desktop app, open Settings > Plugins, search for Apify, select Install, and sign in from Settings > MCP servers. More: how to add an MCP server to VS Code.

Option 2: add the hosted server by hand

If your client is not in the plugin list, or you only want the MCP server, add https://mcp.apify.com directly. On first connection your browser opens so you can sign in and approve access. For a client-specific config, use the MCP configurator: pick the Actors and tools you need, then copy the generated configuration. If you use the Apify CLI, apify mcp install <client> writes the configuration for you, for example apify mcp install cursor. The same command works for claude-code, vscode, codex, kiro and antigravity.

Claude Code

claude mcp add apify "https://mcp.apify.com" -t http

Claude Code opens the Apify sign-in page the first time it uses the server.

Cursor and other JSON-config clients

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

VS Code (GitHub Copilot)

{
  "servers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com"
    }
  }
}

Bearer token instead of OAuth

To authorize without signing in, send your Apify API token as a Bearer header. Keep the token in an environment variable, not in the file, when your client supports that:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Claude Desktop and claude.ai

Add https://mcp.apify.com as a custom connector and sign in when asked. Don't put the URL in claude_desktop_config.json, which is for local servers. Apify is also in Claude's connector directory. Steps: how to add an MCP server to Claude Desktop.

Option 3: run the server locally

If your client doesn't support remote MCP servers, you can run the server on your machine over stdio. This needs Node.js 22 or later and an Apify API token (or a token saved by apify login). Actors still run and store their results on the Apify platform. The local server does not infer output schemas for Actor results; the hosted server does.

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

If your client only supports local servers, you can also bridge it to the hosted URL with npx mcp-remote https://mcp.apify.com. Use the hosted server unless you have a reason to run the process locally.

Choose which tools load

Add a tools query parameter to the hosted URL, or pass --tools to the local server, to load only the categories, tool names and Actor names you list. When you set it, the defaults are dropped. A default configuration can change between versions, so for production Apify recommends setting tools explicitly:

https://mcp.apify.com?tools=actors,docs,apify/web-search,apify/web-fetch

npx @apify/actors-mcp-server --tools actors,docs,apify/web-search,apify/web-fetch

To expose a single Actor, list only that Actor, for example https://mcp.apify.com?tools=apify/instagram-scraper. The agent also gets the run and storage tools it needs to read the results.

These tools work without an Apify account: search-actors, fetch-actor-details, search-apify-docs, fetch-apify-docs, apify-api-search and apify-api-details. This URL connects without a token:

https://mcp.apify.com?tools=search-actors,fetch-actor-details,search-apify-docs,fetch-apify-docs

If the tools parameter includes any other tool, or you connect to the default endpoint, the server requires authentication. To cap what a run can cost, pass maxTotalChargeUsd (pay-per-event Actors) or maxItems (pay-per-result Actors) in the callOptions of call-actor. timeout and memory limit the run's duration and memory, not its price. Watch usage in Apify Console.

apify/web-search replaced apify/rag-web-browser in the default tools. To keep the older Actor, add apify/rag-web-browser to your tools list.

Telemetry

Telemetry is on by default. The server collects anonymous information about tool usage (calls, success or failure, duration) and MCP client attributes (name, version, capabilities). It does not collect conversations, arguments passed to tools, API tokens or personal data. To opt out on the hosted server, add telemetry-enabled=false to the URL:

https://mcp.apify.com?telemetry-enabled=false

For the local server, pass --telemetry-enabled=false or set TELEMETRY_ENABLED=false. If both are set, the CLI flag wins.

Check that it works

Open your client's MCP status or tool list and confirm the Apify server is connected and signed in if you need to run Actors. Then try a read-only prompt first, such as: "Search Apify Store for an Actor that extracts product prices from Amazon and show me its input schema and pricing before running it." Start a new conversation if you just finished sign-in and the tools don't appear yet.

Running an Actor costs money on your Apify account. Ask the agent to show the Actor's pricing before it starts a run, and set run limits when you care about the cost.

Troubleshooting

• Authentication fails: reconnect so the client repeats the OAuth flow, or switch to a Bearer token. For the local server, check that APIFY_TOKEN is set in the client's server configuration, not only in your shell.
• The local server won't start: the package requires Node.js 22 or later. Check with node -v.
• VS Code says the OAuth app is not registered: run Authentication: Remove Dynamic Authentication Providers, select Apify, and sign in again.
• `call-actor` fails because of invalid input: the error includes the Actor's input schema so the agent can correct the input and retry.
• Claude Desktop shows the server as connected but no tools appear: check that Apify tools are set to Always allow or Ask first, not blocked. Restart Claude Desktop after configuration changes, and if you use the Desktop extension, remove and re-add it. Logs are in ~/Library/Logs/Claude/ (macOS), ~/.config/Claude/logs/ (Linux) or %APPDATA%\Claude\logs\ (Windows); look for files with mcp in the name.
• An Actor run is slow or seems stuck: Actor runs can take time. Check the Actor's logs in Apify Console.

FAQ

Is the Apify MCP server free?

Connecting is free, and the discovery and docs tools above work without an account. Actor runs bill to your Apify account at each Actor's price. The free plan includes $5 of monthly platform usage.

Do I need an API token?

Not with the hosted server, because OAuth signs you in through the browser. Use a token for the local server, for CI, or when you don't want a browser sign-in. Get it from the API & Integrations section in Apify Console.

Should I use the plugin or add the server by hand?

Use the plugin in Claude Code, Cursor, Codex, GitHub Copilot and VS Code if you want Agent Skills as well as the MCP server. Add the URL by hand if your client has no plugin, or you only want the server.

Should I use the hosted or local server?

The hosted server with OAuth is the recommended option: there's nothing to install, and it infers output schemas for Actor results. Use the local server when your client only supports stdio, or you want the MCP process on your own machine. Actors still run on the Apify platform in both modes.