Apify Model Context Protocol (MCP) Server

Overview

This document details the Apify Model Context Protocol (MCP) Server, an implementation designed to bridge MCP-compliant clients (such as AI agents and applications) with the extensive library of Apify Actors. It enables seamless interaction, allowing AI agents to leverage any Apify Actor as a functional tool for data extraction, web automation, and other tasks.

The server supports two primary operational modes:

Apify Platform Actor (SSE Transport): Deployed as a managed Actor on the Apify platform, accessible via an HTTP endpoint utilizing Server-Sent Events (SSE) for communication. Refer to the Platform Actor Guide.
Local Execution (Stdio Transport): Executed locally as a process, communicating with clients via standard input/output (stdio) streams. Refer to the Local Execution Guide.

A dedicated Tester MCP Client is available for interactive testing and exploration of the server's capabilities, particularly its SSE interface and dynamic tool management features.

Core Functionality

The primary function of the Apify MCP Server is to dynamically expose specified Apify Actors as tools consumable by MCP clients. This allows AI assistants or agentic frameworks to programmatically invoke Actors to perform tasks such as:

Scraping Facebook content using Facebook Posts Scraper.
Extracting contact details from Google Maps via Google Maps Email Extractor.
Retrieving Google Search results with Google Search Results Scraper.
Interacting with Instagram using Instagram Scraper.
Performing web searches and content extraction using the RAG Web Browser.

The server handles the translation between MCP tool calls and Apify Actor executions, including mapping parameters and returning results.

Architecture Diagram: Apify MCP Server Interaction Flow (Diagram illustrating the interaction between MCP clients, the Apify MCP Server, and the Apify Platform/Actors)

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard facilitating secure and structured communication between AI applications (including agents) and external tools, data sources, or resources. This server leverages MCP to provide a standardized interface to Apify's capabilities. Further details can be found on the MCP website and in the introductory article: What is MCP and why does it matter?.

Relation to AI Agents

By exposing Apify Actors via MCP, this server empowers AI Agents and frameworks compatible with the protocol. Agents can utilize the vast array of Apify Actors as readily available tools for data gathering, web interaction, and complex task execution, enhancing their capabilities significantly.

For further reading on AI Agents and their ecosystem on Apify:

Server Components

Tools

Actor Tools

Any public Apify Actor can be exposed as an MCP tool. The server configuration dictates which Actors are initially available. By default, without specific configuration, the server loads:

apify/instagram-scraper
apify/rag-web-browser
lukaskrivka/google-maps-with-contact-details

The server dynamically introspects the input schema of each configured Actor (e.g., RAG Web Browser Input Schema) and generates a corresponding MCP tool definition.

Tool Name: The full Actor name (e.g., apify/rag-web-browser).
Tool Arguments: Directly mapped from the Actor's input schema fields.

Example Tool Call (Conceptual): An MCP client requesting to use the apify/rag-web-browser tool might generate a call structure like:

{
  "tool_name": "apify/rag-web-browser",
  "tool_input": {
    "query": "restaurants in San Francisco",
    "maxResults": 3
  }
}

The underlying Large Language Model (LLM) within the AI agent typically determines the appropriate Actor (tool) and necessary arguments based on the user's request. The MCP server then executes the corresponding Actor with the provided input. Refer to individual Actor documentation for detailed input parameters.

Helper Tools

The server includes built-in helper tools for Actor discovery and management:

get-actor-details: Retrieves metadata, documentation, and input schema for a specified Actor.
discover-actors: Facilitates searching the Apify Store for relevant Actors based on keywords.

Dynamic Tool Management Tools

These tools allow for modifying the available toolset during runtime. Note: Effective use requires the MCP client to support ToolListChangedNotificationSchema notifications, which is not universally implemented across all clients. The Apify Tester MCP Client supports this functionality when the server's enableActorAutoLoading parameter is enabled.

add-actor-as-tool: Adds a specified Actor to the list of available tools. Requires subsequent user consent for execution.
remove-actor-from-tool: Removes a specified Actor from the available tools list.

Prompts & Resources

Currently, this server implementation does not expose any MCP Prompts or Resources. Future enhancements plan to integrate Apify Datasets and Key-Value Stores as MCP Resources.

Operational Modes & Usage

Choose the operational mode that best suits your integration needs.

Apify Platform Actor (SSE Transport)

This mode runs the MCP server as a continuously operating Apify Actor in Standby mode, providing an HTTP endpoint for Server-Sent Events (SSE) communication.

Server Invocation

Default Actors: Initiate the server with the default Actor set by sending an HTTP GET request (requires authentication):
```
[https://actors-mcp-server.apify.actor/sse?token=](https://actors-mcp-server.apify.actor/sse?token=)<YOUR_APIFY_TOKEN>
```
Replace <YOUR_APIFY_TOKEN> with your valid Apify API token.
Custom Actors: To use a specific set of Actors, first create an Actor Task for the apify/actors-mcp-server Actor, configuring the desired Actors in the task's input. Then, invoke the task-specific endpoint:
```
https://<YOUR_USERNAME>--<YOUR_TASK_NAME>.apify.actor/sse?token=<YOUR_APIFY_TOKEN>
```
Refer to the Apify Store for available Actors.

SSE Interaction Protocol

Clients interact with the running server via Server-Sent Events.

Establish Connection: Send an HTTP GET request to the server's /sse endpoint (as shown above). The server responds with an initial event establishing the connection and providing a sessionId.
```
# Example SSE event from server
event: endpoint
data: /message?sessionId=<GENERATED_SESSION_ID>
```

Send MCP Messages: Send MCP requests (e.g., tools/call) via HTTP POST to the /message endpoint, including the sessionId and token as query parameters.

curl -X POST "[https://actors-mcp-server.apify.actor/message?token=](https://actors-mcp-server.apify.actor/message?token=)<YOUR_APIFY_TOKEN>&sessionId=<GENERATED_SESSION_ID>" \
     -H "Content-Type: application/json" \
     -d '{
          "jsonrpc": "2.0",
          "id": 123,
          "method": "tools/call",
          "params": {
            "name": "lukaskrivka/google-maps-with-contact-details",
            "arguments": { "searchStringsArray": ["restaurants in San Francisco"], "maxCrawledPlacesPerSearch": 3 }
          }
        }'

The server will acknowledge receipt (e.g., HTTP 202 Accepted).

Receive Responses: The server processes the request (invoking the specified Actor) and streams results back to the client via SSE message events.

# Example SSE response event from server
event: message
data: {"jsonrpc":"2.0","id":123,"result":{"content":[{"type":"text","text":"{\"searchString\":\"restaurants in San Francisco\",\"rank\":1,\"title\":\"Gary Danko\",...}"}]}}

Client Compatibility: While SSE is a standard, robust client support varies (as of early 2025). The Apify Tester MCP Client fully supports this mode. Clients like Claude Desktop do not currently support SSE transport; use the Local Stdio Execution for such clients. Example Python client: [`c...