Skip to content

Commit c9ae46e

Browse files
TC-MOdavidjohnbarton
TC-MO
and
davidjohnbarton
authored
docs: add mcp integration doc (#1546)
Co-authored-by: davidjohnbarton <[email protected]>
1 parent 05d1a23 commit c9ae46e

File tree

1 file changed

+185
-0
lines changed
  • sources/platform/integrations/ai

1 file changed

+185
-0
lines changed

‎sources/platform/integrations/ai/mcp.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
title: Apify MCP server
3+
sidebar_label: Apify MCP server
4+
description: Learn how to use the Apify MCP server to integrate Apify Actors into your AI agents or applications.
5+
sidebar_position: 1
6+
slug: /integrations/mcp
7+
---
8+
9+
<!-- markdownlint-disable MD024 -->
10+
11+
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).
12+
13+
## Why use MCP with Apify?
14+
15+
- _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).
19+
20+
## Common use cases
21+
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+
26+
## Prerequisites
27+
28+
Before you start, make sure you have the following:
29+
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).
32+
33+
## Connection methods
34+
35+
Apify provides two main ways to connect your MCP client to Actors:
36+
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.
39+
40+
### Option 1: Use the main Actors MCP server
41+
42+
This method offers the most flexibility, allowing access to all of Apify Store dynamically or by specifying Actors at connection time.
43+
44+
```text title="Server endpoint"
45+
https://actors-mcp-server.apify.actor/sse?token=<YOUR_API_TOKEN>
46+
```
47+
48+
Key features:
49+
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`).
53+
54+
The following example demonstrates connecting to the main server while pre-registering the `apify/rag-web-browser` Actor.
55+
56+
#### Step 1: Start the SSE connection
57+
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.
59+
60+
```bash
61+
# Start the Server-Sent Events (SSE) session and keep it active
62+
curl "https://actors-mcp-server.apify.actor/sse?token=<YOUR_API_TOKEN>&actors=apify/rag-web-browser"
63+
64+
# The server responds with the session endpoint. Note the sessionId.
65+
# event: endpoint
66+
# data: /message?sessionId=9d820491-38d4-4c7d-bb6a-3b7dc542f1fa
67+
```
68+
69+
#### Step 2: Send a tool call request
70+
71+
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",
83+
"proxyConfiguration": {
84+
"useApifyProxy": true
85+
},
86+
"removeElementsCssSelector": "nav, footer, script, style, noscript, svg, img[src^='\''data:'\''],\\n[role=\\"alert\\"],\\n[role=\\"banner\\"],\\n[role=\\"dialog\\"],\\n[role=\\"alertdialog\\"],\\n[role=\\"region\\"][aria-label*=\\"skip\\" i],\\n[aria-modal=\\"true\\"]",
87+
"htmlTransformer": "none"
88+
},
89+
"name": "apify/rag-web-browser"
90+
}
91+
}'
92+
93+
# The server immediately confirms receipt of the request:
94+
# Accepted
95+
```
96+
97+
#### Step 3: Receive the result via SSE
98+
99+
The Actor's result is sent back asynchronously over the SSE connection established in Step 1.
100+
101+
```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
109+
}
110+
]
111+
}
112+
}
113+
```
114+
115+
### Option 2: Use an Actor-specific MCP server
116+
117+
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 &#96;apify/rag-web-browser&#96;"
120+
https://rag-web-browser.apify.actor/sse?token=<YOUR_API_TOKEN>
121+
```
122+
123+
:::note
124+
125+
The hostname typically matches the Actor's name.
126+
127+
:::
128+
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.
130+
131+
The following example demonstrates use of `rag-web-browser` server.
132+
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
139+
curl "https://rag-web-browser.apify.actor/sse?token=<YOUR_API_TOKEN>"
140+
141+
# 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+
```
175+
176+
## Testing and resources
177+
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/)
185+

0 commit comments

Comments
 (0)