On this page

Apify MCP server

The Apify's MCP server (mcp.apify.com) allows AI applications and agents to interact with the Apify platform using Model Context Protocol (MCP). The MCP server enables AI agents to discover and run Actors from Apify Store, access storages and results, and enables AI coding assistants to access Apify documentation and tutorials.

Help keep this page up to date

This integration uses a third-party service. If you find outdated content, please submit an issue on GitHub.

Apify MCP server vs MCP connectors

This page covers the Apify MCP server, which exposes Apify Actors as tools to outside AI clients. If you are building an Actor that needs to call third-party MCP servers (such as Notion or Slack) on a user's behalf, see MCP connectors instead.

Apify AI vs the MCP server

The Apify MCP server and Apify AI share the same Actor search and execution backend, but they serve different audiences:

MCP server - a programmatic interface for external AI agents, IDEs, and CLIs. Use it when you build or operate your own agent.
Apify AI - the conversational interface inside Apify Console for users who interact with Apify through a chat UI rather than their own agent.

Actor ranking on both surfaces uses parameters similar to those evaluated by the Actor quality score, so Actors with higher quality scores tend to rank higher.

Excluded Actors

The MCP server intentionally excludes two categories of Actors from search and execution:

Full-permission Actors - excluded for security. Running a full-permission Actor is a decision you approve personally, so an LLM can't make it on your behalf.
Rental Actors - excluded because their subscription-based model doesn't fit the sporadic, on-demand way the MCP server runs Actors.

Prerequisites

Before connecting your AI to Apify, you'll need three things:

An Apify account - Sign up for an Apify account, if you don't have one.
Apify API token - Get your API token from the API & Integrationssection inApify Console. This token authorizes the MCP server to run Actors on your behalf. Make sure to keep it secure.
MCP client - An AI agent or client that supports Model Context Protocol (MCP) This could be Anthropic's Claude for Desktop, a VS Code extension with MCP support, or any application that implements the MCP specification. The official MCP documentation maintains a list of compatible clients.

Connect and authorize

You can connect to the Apify MCP server in two ways: use our hosted service using Streamable HTTP with OAuth, or run the server locally for development and testing using local stdio.

Structured output schemas

The hosted Apify MCP server at https://mcp.apify.com supports output schema inference for structured Actor results. Actor tools automatically include inferred output schemas with field-level type information. This helps AI agents understand the expected result structure before calling an Actor. The local stdio server does not support this feature.

Streamable HTTP with OAuth (recommended)

Add https://mcp.apify.com to your MCP client. On first connection, your browser opens so you can sign in to Apify and approve access. To authorize without signing in, use your Apify API token instead.

OAuth
Bearer token

This flow authorizes the server without putting your API token in the client configuration.

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

You can also use your Apify token directly, instead of OAuth, by setting the Authorization: Bearer <APIFY_TOKEN> header in the MCP server configuration.

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

Replace <APIFY_TOKEN> with your actual Apify API token from the API & Integrations section.

Quick setup options

MCP server configuration for other clients: Use the UI configuration tool to select Actors and tools, then copy the configuration to your client.

Client configuration

Here's how to add the Apify MCP server to popular text editors and AI assistants:

Cursor
VS Code
Claude Desktop
Apify CLI

One-click installation

The Apify UI configurator offers a one-click install button for Cursor that automatically applies the configuration to your client.

To add Apify MCP server to Cursor manually:

Create or open the .cursor/mcp.json file.

Add the following to the configuration file:

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

To use a bearer token instead of signing in, add an Authorization header with your Apify API token:

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

One-click installation

The Apify UI configurator offers a one-click install button for VS Code that automatically applies the configuration to your client.

VS Code supports MCP through GitHub Copilot's agent mode (requires Copilot subscription):

Ensure you have GitHub Copilot installed
Open Command Palette (CMD/CTRL + Shift + P) and run MCP: Open User Configuration command.
- This will open mcp.json file in your user profile. If the file does not exist, VS Code creates it for you.

Add the following to the configuration file:

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

To use a bearer token instead of signing in, add an Authorization header with your Apify API token:

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

Add a custom connector 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.

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.

Use the Apify CLI to add the Apify MCP server to a supported local client:

apify mcp install cursor

Available clients are: claude-code, cursor, vscode, vscode-insiders, codex, kiro, and antigravity.

The command creates or updates a user-level MCP server entry named apify. For Cursor, Kiro, and Antigravity, it writes to the client's MCP config file. For Claude Code, VS Code, VS Code Insiders, and Codex CLI, it uses the client's own install command.

By default, the command uses the API token saved by apify login. To use a different token or Apify account than the one configured in the Apify CLI, pass --token <APIFY_TOKEN>:

apify mcp install cursor --token <APIFY_TOKEN>

Use --tools to expose only selected tools or Actors:

apify mcp install vscode --tools search-actors,apify/rag-web-browser

Local stdio

If your client doesn't support remote MCP servers using the https://mcp.apify.com URL, you can run the server locally instead. This method uses the stdio transport to connect directly through your local environment.

Add this to your configuration file:

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

The server will download automatically on first use and connect using your API token.

Tool selection

By default, the MCP server loads the actors and docs tool categories, the apify/rag-web-browser and apify/web-fetch Actors, and report-problem. You can customize which tools are available by adding parameters to the server URL:

https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser

For minimal setups where you only need specific Actors:

https://mcp.apify.com?tools=apify/instagram-scraper,apify/google-search-scraper

This configuration approach works for both hosted and local setups. For the CLI version:

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

Easy configuration

Use the UI configurator https://mcp.apify.com/ to select your tools visually, then copy the configuration to your client.

Anonymous access

The Apify MCP server accepts requests without an API token when the tools query parameter contains only tools enabled for unauthenticated use. These tools cover Actor discovery and documentation lookup:

search-actors
fetch-actor-details
search-apify-docs
fetch-apify-docs

For example, the following URL connects without authentication:

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 an API token. Running Actors and accessing storage or run data always requires authentication.

Available tools

Tool name	Category	Description
`search-actors`	`actors`	Search for Actors in Apify Store
`fetch-actor-details`	`actors`	Retrieve detailed information about a specific Actor, including its input and output schema, README (summary when available, full otherwise), and pricing
`call-actor`	`actors`	Run an Actor and wait up to `waitSecs` (0-45, default 30) for it to finish. Returns the run status and storage IDs, not the results themselves
`apify/rag-web-browser`	Actor	Browse and extract web data
`apify/web-fetch`	Actor	Fetch one http(s) URL and return its full content, rendering JavaScript and bypassing anti-bot protection
`search-apify-docs`	`docs`	Search the Apify documentation for relevant pages
`fetch-apify-docs`	`docs`	Fetch the full content of an Apify documentation page by its URL
`get-actor-run`	`runs`	Get detailed information about a specific Actor run
`get-actor-run-list`	`runs`	Get a list of an Actor's runs, filterable by status
`get-actor-run-log`	`runs`	Retrieve the logs for a specific Actor run
`abort-actor-run`	`runs`	Abort a running Actor run
`get-dataset`	`storage`	Get metadata about a specific dataset
`get-dataset-items`	`storage`	Retrieve items from a dataset with support for filtering and pagination
`get-dataset-schema`	`storage`	Generate a JSON schema from dataset items
`get-key-value-store`	`storage`	Get metadata about a specific key-value store
`get-key-value-store-keys`	`storage`	List the keys within a specific key-value store
`get-key-value-store-record`	`storage`	Get the value associated with a specific key in a key-value store
`get-dataset-list`	`storage`	List all available datasets for the user
`get-key-value-store-list`	`storage`	List all available key-value stores for the user
`get-actor-task`	`tasks`	Get a saved Actor task, its publication state, and its public display configuration
`create-actor-task`	`tasks`	Create a saved Actor task: a named, reusable Actor configuration
`update-actor-task`	`tasks`	Update a task's input, run options, or the display configuration of its landing page
`publish-actor-task`	`tasks`	Publish a task on its public landing page
`unpublish-actor-task`	`tasks`	Unpublish a task from its public landing page
`create-schedule`	`schedules`	Create a schedule that runs Actors and tasks on a cron cadence
`get-schedule`	`schedules`	Get a schedule's cron expression, time zone, state, and next run
`update-schedule`	`schedules`	Change a schedule's cron expression, time zone, state, or actions
`delete-schedule`	`schedules`	Delete a schedule permanently
`report-problem`	`dev`	Report a problem with the MCP server to Apify

Retrieving Actor results

call-actor returns the run's status and storage IDs, not its output. To read the results, use get-dataset-items with the datasetId from the run. It supports limit, offset, and field filtering.

Whenever call-actor or a specific Actor tool such as apify--rag-web-browser is loaded, the server also adds get-actor-run, get-dataset-items, get-key-value-store-record, and abort-actor-run, even if you didn't select them. A default configuration therefore exposes them too.

Find and call any Actor on demand

Your AI can search Apify Store for relevant Actors using the search-actors tool, inspect Actor details to understand required inputs, and call any Actor by name using call-actor - without needing to pre-configure it. This means your AI can adapt to new tasks without manual configuration.

Agentic payments

Agentic payments allow AI agents to autonomously pay for Actor runs without requiring an Apify API token:

AGI - buy a prepaid Apify API token from Apify AGI with an x402 or MPP payment, then use it against this MCP server or the Apify API directly. Recommended for most agents - works for any Actor, not just Pay Per Event ones.
Skyfire - managed payment tokens through the Skyfire payment platform.

The MCP server also has its own Direct x402 support (per-request, no minted token, Pay Per Event Actors only) via mcpc - see the Apify MCP Server README for setup.

For setup instructions and details, see the individual integration pages.

Telemetry

The MCP server collects telemetry data about tool calls and MCP clients to help Apify understand usage patterns and improve the service. Participation in this program is optional and you may opt out if you prefer not to share any information.

Data collection

All telemetry data is collected and stored securely. We do not collect any sensitive information such as conversations, arguments passed to tools, API tokens, or personal data.

The server collects anonymous information about tool usage, including:

Basic information about used tools (calls, success/failure, duration)
MCP client attributes (client name, version, capabilities)

By default, telemetry is enabled for all tool calls.

Opt out of telemetry

Remote server

For the remote server (mcp.apify.com), you can opt out of telemetry by adding the telemetry-enabled=false query parameter to the server URL:

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

Local stdio server

For the local stdio server, opt out of telemetry using a CLI flag or an environment variable. When both the CLI flag and environment variable are set, the CLI flag takes precedence.

CLI flag: set the --telemetry-enabled CLI flag to false:

npx @apify/actors-mcp-server --telemetry-enabled=false

Environment variable: set the TELEMETRY_ENABLED environment variable to false:
```
export TELEMETRY_ENABLED=false
npx @apify/actors-mcp-server
```

Advanced usage

Production best practices

For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates:

https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser
For a local stdio server, always use the latest version of the server by appending @latest to your npm commands.
Monitor your API usage through Apify Console to stay within your plan limits.

Rate limits and performance

The Apify MCP server allows up to 30 requests per second per user. This limit applies to all operations including Actor runs, storage access, and documentation queries. If you exceed this limit, you'll receive a 429 response and should implement appropriate retry logic.

Troubleshooting

Claude Desktop issues

For Claude Desktop-specific troubleshooting (tools not loading, connection errors, corrupted cache), see Claude Desktop troubleshooting.

Authentication errors

Check your API token: Verify that your Apify API token is correct. You can find it in the API & Integrations section of the Apify Console. Without a valid token, the server cannot start Actor runs.
Set environment variable for local development: When running the MCP server locally, ensure you have set the APIFY_TOKEN environment variable.

Local environment setup

The MCP server requires Node.js v18 or higher. Check your installed version by running node -v in your terminal.
Using the latest server version: To ensure you have the latest features and bug fixes, use the latest version of the @apify/actors-mcp-server package. You can do this by appending @latest to the package name in your npx command or configuration file.

Actor execution issues

No response or long delays: Actor runs can take time to complete depending on their task. If you're experiencing long delays, check the Actor's logs in Apify Console. The logs will provide insight into the Actor's status and show if it's processing a long operation or has encountered an error.

Support and resources

The Apify MCP server is an open-source project. Report bugs, suggest features, or ask questions in the GitHub repository.

If you find this project useful, please star it on GitHub to show your support!

To learn more about MCP and Apify integration:

Model Context Protocol specification - 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 - Learn how to expose over thousands of Apify Actors to AI agents with Claude and LangGraph, and configure MCP clients and servers.
Video tutorial - Integrate thousands of Apify Actors and Agents with Claude.
Apify 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.