You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Apify Model Context Protocol (MCP) server allows AI agents and frameworks compatible with the MCP standard to connect with the extensive library of Actors available on [Apify Store](https://apify.com/store).
11
+
The _Apify Model Context Protocol (MCP) Server_ allows AI applications to connect to Apify’s extensive library of Actors as tools to perform web scraping, data extraction, or other automation tasks in real time.
-_Access a vast tool library_: Provide AI agents access to thousands of pre-built Actors for web scraping, data extraction, and automation.
16
-
-_Dynamic tool discovery_: Unlike static OpenAPI definitions, MCP enables agents to dynamically find and add relevant Actors to their context during runtime. Agents can use MCP operations like `discover-actors` and `add-actor-to-tools`.
17
-
-_Scalability_: Efficiently manage access to a large and growing number of tools, which is challenging with single, static API definitions.
18
-
-_Flexible integration_: Connect to the MCP server using HTTP Server-Sent Events (SSE) or local standard input/output (stdin/stdout). Compatible clients include Claude Desktop, LibreChat, and [Apify’s Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client).
15
+
## Quickstart
19
16
20
-
## Common use cases
17
+
You can use the Apify MCP Server in two ways:
18
+
19
+
-_Standard Input/Output (stdio)_: Ideal for local integrations and command-line tools such as the Claude desktop client.
20
+
- Set MCP client server command to `npx @apify/actors-mcp-server` and environment variable `APIFY_TOKEN` to your Apify API token
21
+
- See `npx @apify/actors-mcp-server --help` for more options
22
+
-_HTTPS Endpoint_[mcp.apify.com](https://mcp.apify.com): Connect your MCP client by including `Authorization: Bearer <APIFY_TOKEN>` header in your requests.
23
+
-`https://mcp.apify.com` for streamable transport
24
+
-`https://mcp.apify.com/sse` for legacy SSE transport
25
+
26
+
You could also use legacy option by running [Apify Actors MCP Server](https://apify.com/apify/actors-mcp-server) as an Actor.
21
27
22
-
- Extract data from websites, such as social media posts, search engine results, or specific URLs.
23
-
- Summarize web content or identify trends.
24
-
- Run automated web workflows without direct user interaction.
25
28
26
29
## Prerequisites
27
30
28
31
Before you start, make sure you have the following:
29
32
30
-
1._Apify account_: You need an active account on the Apify platform.
31
-
2._API Token_: Get your personal API token from the **Integrations** section in [Apify Console](https://console.apify.com/account#/integrations).
33
+
1._An Apify account:_ Sign up for a free Apify account if you don’t have one.
34
+
1._Apify API Token:_ Get your personal API token from the **Integrations** section in [Apify Console](https://console.apify.com/account#/integrations). This token will be used to authorize the MCP server to run Actors on your behalf.
35
+
1._MCP client:_ An AI agent or client that supports MCP. This could be Anthropic Claude desktop, a VS Code extension with MCP support, Apify’s web-based Tester MCP Client, or any custom client implementation. See supported MCP clients in [official documentation](https://modelcontextprotocol.io/clients).
32
36
33
-
## Connection methods
37
+
## Example usage (local stdio with Claude desktop)
34
38
35
-
Apify provides two main ways to connect your MCP client to Actors:
39
+
Let’s walk through an example of using Claude desktop with the Apify MCP Server:
36
40
37
-
1. Main Actors MCP Server: Access _all_ public Actors. Requires dynamic discovery or specifying Actors via URL parameters.
38
-
2. Actor-specific MCP Server: A dedicated endpoint for a _single_ Actor, which is pre-registered and ready for immediate use.
41
+
1._Configure Claude desktop:_ Claude desktop supports MCP servers via the **Developer settings**. You need to add an entry for the Apify MCP server. For instance, in Claude’s config file, under `mcpServers`, add an entry like:
39
42
40
-
### Option 1: Use the main Actors MCP server
43
+
```json
44
+
{
45
+
"mcpServers": {
46
+
"actors-mcp-server": {
47
+
"command": "npx",
48
+
"args": ["-y", "@apify/actors-mcp-server"],
49
+
"env": {
50
+
"APIFY_TOKEN": "YOUR_APIFY_TOKEN"
51
+
}
52
+
}
53
+
}
54
+
}
55
+
```
41
56
42
-
This method offers the most flexibility, allowing access to all of Apify Store dynamically or by specifying Actors at connection time.
57
+
This tells Claude to spawn the Apify MCP Server (via the [Actors MCP Server](https://www.npmjs.com/package/@apify/actors-mcp-server) NPM package with your API token (on the first run, it will download the package automatically).
1. _Launch Claude and connect:_ After updating the config, restart Claude desktop. If successful, Claude will show a “plugin” (often indicated by a plug icon 🔌) signifying it connected to the Apify Actors MCP server.
47
60
48
-
Key features:
61
+
1. _Use the Actors in conversation:_ You can chat with Claude and ask it to use Apify Actors. For example: _“What Apify Actors can I use?”_ Claude will list available tools via the MCP server. If none are pre-loaded, it may show defaults or guide you to find more.
49
62
50
-
- Dynamic discovery: Agents can use MCP operations like `discover-actors` to search Apify Store for tools.
51
-
- Dynamic registration: Agents can use the `add-actor-to-tools` operation to add discovered Actors to their available toolset for the current session.
52
-
- Pre-registration via URL: You can make specific Actors available immediately by adding the `&actors=` query parameter to the connection URL (for example, `&actors=apify/rag-web-browser`).
63
+
_(If you prefer not to set up Claude desktop, you can achieve a similar result using [Apify’s Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client), which provides a web UI to test the MCP server.)_
53
64
54
-
The following example demonstrates connecting to the main server while pre-registering the `apify/rag-web-browser` Actor.
65
+
55
66
56
-
#### Step 1: Start the SSE connection
67
+
## Interact with the MCP server over SSE
57
68
58
-
Use `curl` or another SSE client to establish the connection. Append `&actors=apify/rag-web-browser` to pre-register the tool. Replace `<YOUR_API_TOKEN>` with your actual Apify API token.
69
+
You can interact with the server through Server-Sent Events (SSE) to send messages and receive responses.
59
70
60
-
```bash
61
-
# Start the Server-Sent Events (SSE) session and keep it active
Use the `sessionId` obtained in Step 1 to send a POST request to the `/message` endpoint. This request invokes the pre-registered `apify/rag-web-browser` tool. Replace `<YOUR_API_TOKEN>` and `<SESSION_ID>` with your actual values.
72
-
73
-
```bash
74
-
curl -X POST "https://actors-mcp-server.apify.actor/message?token=<YOUR_API_TOKEN>&session_id=<SESSION_ID>" \
75
-
-H "Content-Type: application/json" \
76
-
-d '{
77
-
"jsonrpc": "2.0",
78
-
"id": 1,
79
-
"method": "tools/call",
80
-
"params": {
81
-
"arguments": {
82
-
"query": "web browser for RAG pipelines -site:reddit.com",
# The server immediately confirms receipt of the request:
94
-
# Accepted
95
-
```
87
+
## Adding Multiple Actors
96
88
97
-
#### Step 3: Receive the result via SSE
89
+
By default, the main Actors MCP Server starts with a single default [RAG Web Browser Actor](https://apify.com/apify/rag-web-browser). However, you can fully customize which Actors are available:
98
90
99
-
The Actor's result is sent back asynchronously over the SSE connection established in Step 1.
91
+
-_Dynamic adding during a session:_ If your client supports it, the agent itself can add Actors dynamically by name (using the `add-actor` operation) at runtime. For example, after using `search-actors` to find an Actor’s name, calling `add-actor` with that name will load it. Note that not all MCP client frameworks allow dynamic tool addition at runtime, but Apify’s own tester client does, if `enableAddingActors` is enabled—either via `?enableAddingActors=true` in the MCP Server URL, or with the CLI flag `--enable-adding-actors` (can also be set in Claude Desktop config args as `--enable-adding-actors`).
92
+
-_Via config file (for Claude desktop):_ When using Claude desktop, you can specify which Actors should be immediately available by configuring your `mcpServers` settings. Add the Actors as a comma-separated list in the `--actors` parameter, as shown in the example below. This pre-loads your selected tools without requiring discovery during conversations, ideal for workflows with predictable tool needs.
100
93
101
94
```json
102
-
event: message
103
-
data: {
104
-
"result": {
105
-
"content": [
106
-
{
107
-
"type": "text",
108
-
"text": "[{\"searchResult\":{\"title\":\"... RAG Web Browser Result ...\",\"description\":\"... Content extracted by the Actor ...\"}}]"// Example structure
Certain Actors, such as `apify/rag-web-browser`, offer their own dedicated MCP server endpoint. This simplifies integration when you only need to interact with that specific Actor.
118
-
119
-
```text title="Endpoint example for `apify/rag-web-browser`"
In summary, you can start with a broad set (everything open and discoverable) or a narrow set (just what you need) and even expand tools on the fly, giving your agent a lot of flexibility without overwhelming it initially.
126
112
127
-
:::
113
+
## Dynamic Actor tooling
128
114
129
-
This method is ideal for integrating a specific tool directly into an application (like Claude Desktop) or a custom client without needing the dynamic discovery capabilities of the main server.
115
+
One of the powerful features of MCP with Apify is **dynamic actor tooling** – the ability for an AI agent to find new tools (Actors) as needed and incorporate them. Here are some special MCP operations and how Apify MCP Server supports them:
130
116
131
-
The following example demonstrates use of `rag-web-browser` server.
117
+
-_Actor discovery and management:_ Search for [Actors](https://docs.apify.com/platform/actors) (`search-actors`), view details (`get-actor-details`), and dynamically add or remove tools (`add-actor`, `remove-actor`).
118
+
-_Actor execution and monitoring:_ Start [Actor runs](https://docs.apify.com/platform/actors/running/runs-and-builds#runs), fetch run results (`get-actor-run`), logs (`get-actor-log`), and abort runs (`abort-actor-run`).
119
+
-_Dataset access:_ List [datasets](https://docs.apify.com/platform/storage/dataset), retrieve dataset info and items (`get-dataset`, `get-dataset-list`, `get-dataset-items`).
120
+
-_Key-value store access:_ List [key-value stores](https://docs.apify.com/platform/storage/key-value-store), view keys, and retrieve records (`get-key-value-store-list`, `get-key-value-store`, `get-key-value-store-keys`, `get-key-value-store-record`).
121
+
-_Built-in help tool:_ A static helper (`apify-actor-help-tool`) that returns usage info for the Apify MCP Server.
132
122
133
-
#### Step 1: Start the SSE connection
134
-
135
-
Connect directly to the Actor's specific MCP endpoint. Replace `<YOUR_API_TOKEN>` with your actual Apify API token.
136
-
137
-
```bash
138
-
# Start the Server-Sent Events (SSE) session and keep it active
# The server responds with the session endpoint. Note the sessionId.
142
-
# event: endpoint
143
-
# data: /message?sessionId=5b2a...
144
-
```
145
-
146
-
#### Step 2: Send a tool call request
147
-
148
-
Use the `sessionId` from Step 1 to send a POST request to the Actor's `/message` endpoint. Replace `<YOUR_API_TOKEN>` and `<SESSION_ID>` with your actual values. The tool `name` in the parameters typically matches the Actor name.
149
-
150
-
```bash
151
-
curl -X POST "https://rag-web-browser.apify.actor/message?session_id=<SESSION_ID>&token=<YOUR_API_TOKEN>" \
152
-
-H "Content-Type: application/json" \
153
-
-d '{
154
-
"jsonrpc": "2.0",
155
-
"id": 1,
156
-
"method": "tools/call",
157
-
"params": {
158
-
"arguments": { "query": "recent news about LLMs", "maxResults": 1 },
159
-
"name": "rag-web-browser"
160
-
}
161
-
}'
162
-
163
-
# The server immediately confirms receipt of the request:
164
-
# Accepted
165
-
```
166
-
167
-
#### Step 3: Receive the result via SSE
168
-
169
-
The result is sent back over the SSE connection established in Step 1.
170
-
171
-
```json
172
-
event: message
173
-
data: {"result":{"content":[{"type":"text","text":"[{\"searchResult\":{\"title\":\"Language models recent news\",\"description\":\"Amazon Launches New Generation of LLM Foundation Model...\"}}]"}]}}
174
-
```
123
+
## Troubleshooting
175
124
176
-
## Testing and resources
125
+
-_Authorization (API Token):_ If the MCP server isn’t executing Actors, ensure you provided a correct Apify API token. Without a valid `APIFY_TOKEN`, the server cannot start Actor runs. Always set the `APIFY_TOKEN` environment variable when running locally.
126
+
-_Ensure latest version:_ If running via NPM, always use the latest version of `@apify/actors-mcp-server` for the newest features and fixes. You can append `@latest` when installing or in your config args to ensure this.
127
+
-_Node.js environment:_ If running the server locally, make sure Node.js is installed and up to date (`node -v`). The MCP server requires Node.js v18+.
128
+
-_No response or long delay:_ Keep in mind that when an Actor tool is called, it may take some time to complete (depending on the task). If nothing is coming back, check the Actor’s logs in Apify console — the Actor might be waiting on a long operation or input.
177
129
178
-
- Testing:
179
-
- Tester MCP Client: Use the [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) on Apify to interact with either MCP server type. Enter the appropriate server URL (for example, `https://actors-mcp-server.apify.actor/sse` or `https://rag-web-browser.apify.actor/sse`) in the Actor input field, configure your API token, run the client Actor, and interact through its user interface.
180
-
- Protocol information:
181
-
- MCP documentation: For details on the protocol, see the [MCP Introduction](https://modelcontextprotocol.io/introduction).
182
-
- MCP client examples: Find example client implementations at [MCP Clients](https://modelcontextprotocol.io/clients).
183
-
- Further reading:
184
-
- Apify Blog: Read more about Apify's implementation in the post: [What is Anthropic's Model Context Protocol?](https://blog.apify.com/what-is-model-context-protocol/)
130
+
## Learn more
185
131
132
+
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction): Learn about the open standard on the official MCP website – understanding the protocol can help you build custom agents.
133
+
-[Apify Actors MCP Server](https://apify.com/apify/actors-mcp-server): The README for the Apify MCP Server actor (available on Apify Store as `apify/actors-mcp-server`) provides technical details on implementation and advanced usage.
134
+
-[Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client): A specialized client actor (`jiri.spilka/tester-mcp-client`) that you can run to simulate an AI agent in your browser. Useful for testing your setup with a chat UI.
135
+
-[How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/): Learn how to expose over 5,000 Apify Actors to AI agents with Claude and LangGraph, and configure MCP clients and servers.
0 commit comments