Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 11 additions & 75 deletions .actor/ACTOR.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Apify Model Context Protocol (MCP) Server

> **⚠️ Legacy solution notice**
> This Actor is legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides.

[![Actors MCP Server](https://apify.com/actor-badge?actor=apify/actors-mcp-server)](https://apify.com/apify/actors-mcp-server)

Implementation of an MCP server for all [Apify Actors](https://apify.com/store).
Expand Down Expand Up @@ -91,18 +94,13 @@ When a tool is called, the arguments are automatically passed to the Actor by th
You can refer to the specific Actor's documentation for a list of available arguments.

### Helper tools
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:

The server provides a set of helper tools to discover available Actors and retrieve their details:
- `get-actor-details`: Retrieves documentation, input schema, and details about a specific Actor.
- `discover-actors`: Searches for relevant Actors using keywords and returns their details.

There are also tools to manage the available tools list. However, dynamically adding and removing tools requires the MCP client to have the capability to update the tools list (handle `ToolListChangedNotificationSchema`), which is typically not supported.

You can try this functionality using the [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) Actor.
To enable it, set the `enableActorAutoLoading` parameter.

- `add-actor-as-tool`: Adds an Actor by name to the available tools list without executing it, requiring user consent to run later.
- `remove-actor-from-tool`: Removes an Actor by name from the available tools list when it's no longer needed.
- Actor discovery and management: Search for Actors (`search-actors`), view details (`get-actor-details`), and dynamically add or remove tools (`add-actor`, `remove-actor`).
- Actor execution and monitoring: Start Actor runs, fetch run results (`get-actor-run`), logs (`get-actor-log`), and abort runs (`abort-actor-run`).
- Dataset access: List datasets, retrieve dataset info and items (`get-dataset`, `get-dataset-list`, `get-dataset-items`).
- Key-value store access: List key-value stores, view keys, and retrieve records (`get-key-value-store-list`, `get-key-value-store`, `get-key-value-store-keys`, `get-key-value-store-record`).
- Built-in help tool: A static helper (`apify-actor-help-tool`) that returns usage info for the Apify MCP Server.

## Prompt & Resources

Expand Down Expand Up @@ -156,44 +154,6 @@ In the client settings, you need to provide server configuration:
}
}
```
Alternatively, you can use [clientSse.ts](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientSse.ts) script or test the server using `curl` </> commands.

1. Initiate Server-Sent-Events (SSE) by sending a GET request to the following URL:
```
curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
```
The server will respond with a `sessionId`, which you can use to send messages to the server:
```shell
event: endpoint
data: /message?sessionId=a1b
```

2. Send a message to the server by making a POST request with the `sessionId`:
```shell
curl -X POST "https://actors-mcp-server.apify.actor/message?token=<APIFY_TOKEN>&session_id=a1b" -H "Content-Type: application/json" -d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"arguments": { "searchStringsArray": ["restaurants in San Francisco"], "maxCrawledPlacesPerSearch": 3 },
"name": "lukaskrivka/google-maps-with-contact-details"
}
}'
```
The MCP server will start the Actor `lukaskrivka/google-maps-with-contact-details` with the provided arguments as input parameters.
For this POST request, the server will respond with:

```text
Accepted
```

3. Receive the response. The server will invoke the specified Actor as a tool using the provided query parameters and stream the response back to the client via SSE.
The response will be returned as JSON text.

```text
event: message
data: {"result":{"content":[{"type":"text","text":"{\"searchString\":\"restaurants in San Francisco\",\"rank\":1,\"title\":\"Gary Danko\",\"description\":\"Renowned chef Gary Danko's fixed-price menus of American cuisine ... \",\"price\":\"$100+\"...}}]}}
```

## ⾕ MCP Server at a local host

Expand All @@ -216,7 +176,7 @@ If not, follow this guide to install Node.js: [Downloading and installing Node.j

#### Claude Desktop

To configure Claude Desktop to work with the MCP server, follow these steps. For a detailed guide, refer to the [Claude Desktop Users Guide](https://modelcontextprotocol.io/quickstart/user).
To configure Claude Desktop to work with the MCP server, follow these steps. For a detailed guide, refer to the [Claude Desktop Users Guide](https://modelcontextprotocol.io/quickstart/user) or watch the [video tutorial](https://youtu.be/gf5WXeqydUU?t=440).

1. Download Claude for desktop
- Available for Windows and macOS.
Expand Down Expand Up @@ -401,31 +361,6 @@ export APIFY_TOKEN=your-apify-token
npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
```

### Installing via Smithery

To install Apify Actors MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@apify/actors-mcp-server):

```bash
npx -y @smithery/cli install @apify/actors-mcp-server --client claude
```

#### Stdio clients

Create an environment file `.env` with the following content:
```text
APIFY_TOKEN=your-apify-token
```
In the `examples` directory, you can find an example client to interact with the server via
standard input/output (stdio):

- [`clientStdio.ts`](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientStdio.ts)
This client script starts the MCP server with two specified Actors.
It then calls the `apify/rag-web-browser` tool with a query and prints the result.
It demonstrates how to connect to the MCP server, list available tools, and call a specific tool using stdio transport.
```bash
node dist/examples/clientStdio.js
```

# 👷🏼 Development

## Prerequisites
Expand Down Expand Up @@ -499,6 +434,7 @@ If you need other features or have any feedback, [submit an issue](https://conso
- [Model Context Protocol](https://modelcontextprotocol.org/)
- [What are AI Agents?](https://blog.apify.com/what-are-ai-agents/)
- [What is MCP and why does it matter?](https://blog.apify.com/what-is-model-context-protocol/)
- [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/)
- [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
- [AI agent workflow: building an agent to query Apify datasets](https://blog.apify.com/ai-agent-workflow/)
- [MCP Client development guide](https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-client-development-guide.md)
Expand Down
3 changes: 0 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# Apify Model Context Protocol (MCP) Server

> **⚠️ Legacy solution notice**
> This Actor is legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides.

[![Actors MCP Server](https://apify.com/actor-badge?actor=apify/actors-mcp-server)](https://apify.com/apify/actors-mcp-server)

Implementation of an MCP server for all [Apify Actors](https://apify.com/store).
Expand Down
Binary file modified docs/actors-mcp-server.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.