From 3246f9ba891db11e07c6dcbf7a2a6e69bdb11acd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 15 Sep 2025 22:35:57 +0200 Subject: [PATCH 01/10] docs: overhaul mcp docs Stremline the prose for clarity & conciseness Remove outdated SSE section Restructure the content Adjusted description in frontmatter --- sources/platform/integrations/ai/mcp.md | 305 ++++++++---------------- 1 file changed, 104 insertions(+), 201 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index e90ef89abd..8e5b402416 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -1,279 +1,182 @@ --- title: Apify MCP server sidebar_label: MCP -description: Learn how to use the Apify MCP server to integrate Apify Actors into your AI agents or applications. +description: Learn how to use the Apify MCP server to integrate Apify's library of Actors into your AI agents or large language model-based applications. sidebar_position: 1 slug: /integrations/mcp --- -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. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -![Apify MCP Server](../../images/apify_mcp_server.png) - -## Quickstart +The _Apify Model Context Protocol (MCP) Server_ enables AI applications to connect to Apify's extensive library of Actors. Tools allowing your AI agents to perform web scraping, data extraction, and automation tasks in real time. -You can use the Apify MCP Server in two ways: - -- _HTTPS Endpoint_ `mcp.apify.com`: Connect your MCP client through OAuth or by including `Authorization: Bearer ` header in your requests. - - `https://mcp.apify.com` for streamable transport -- _Standard Input/Output (stdio)_: Ideal for local integrations and command-line tools such as the Claude for Desktop client. - - Set MCP client server command to `npx @apify/actors-mcp-server` and environment variable `APIFY_TOKEN` to your Apify API token - - See `npx @apify/actors-mcp-server --help` for more options +![Apify MCP Server](../../images/apify_mcp_server.png) -:::tip Quick setup options -_MCP server configuration for other clients_: Use https://mcp.apify.com to select Actors and tools, then copy the configuration to your client. +## Prerequisites -_Claude Desktop_: Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation. +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 **Integrations** section in [Apify Console](https://console.apify.com/account#/integrations). 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](https://modelcontextprotocol.io/clients) maintains a list of compatible clients. -## Prerequisites +## Quick start -Before you start, make sure you have the following: +To get started with the Apify MCP server you have two options. -1. _An Apify account:_ Sign up for a free Apify account if you don’t have one. -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. -1. _MCP client:_ An AI agent or client that supports MCP. This could be Anthropic Claude for 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). +### Streamable HTTP with OAuth (recommended) -## Example usage (Streamable HTTP with OAuth) +Provide the server URL `https://mcp.apify.com`. You will be redirected to your browser to sign in to your Apify account and approve the connection. -We recommend connecting through OAuth for a secure and simple authentication process. + + -During setup, provide the server URL `https://mcp.apify.com`. You will then be redirected to your browser to sign in to your Apify account and approve the connection. The configuration steps may vary slightly depending on your MCP client. +When you connect for the first time, you'll be redirected to your browser to sign in to Apify and authorize the connection. This OAuth flow ensures secure +authentication without exposing your API token. ```json + { - "mcpServers": { - "apify": { - "url": "https://mcp.apify.com" - } - } +"mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } +} } ``` -You can also use your Apify token directly, instead of OAuth, by setting the `Authorization: Bearer ` header in the MCP server configuration: + + + +You can also use your Apify token directly, instead of OAuth, by setting the `Authorization: Bearer ` header in the MCP server configuration. ```json { - "mcpServers": { - "apify": { - "url": "https://mcp.apify.com", - "headers": { - "Authorization": "Bearer your-apify-token" - } - } - } +"mcpServers": { +"apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer your-apify-token" + } +} +} } ``` -## Example usage (local stdio with Claude for Desktop) - -Let’s walk through an example of using Claude for Desktop with the Apify MCP Server: - -1. _Configure Claude for Desktop:_ Enable 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: - - ```json - { - "mcpServers": { - "actors-mcp-server": { - "command": "npx", - "args": ["-y", "@apify/actors-mcp-server"], - "env": { - "APIFY_TOKEN": "YOUR_APIFY_TOKEN" - } - } - } - } - ``` - - 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 for Desktop. If successful, Claude will show a “plugin” (often indicated by a plug icon 🔌) signifying it connected to the Apify Actors MCP server. + + -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. +:::tip Quick setup options -:::note Web-based alternative +_MCP server configuration for other clients_: Use the [UI configuration tool](https://mcp.apify.com/) to select Actors and tools, then copy the configuration to your client. -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.) +_Claude Desktop_: Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation. ::: -![Apify Tester MCP Client](../../images/chat-ui.webp) +### Local stdio -## Interact with the MCP server over legacy SSE transport +For development environments or Claude Desktop, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing. -:::caution Legacy SSE transport is discouraged - -We strongly recommend using the latest [streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) for new integrations at `https://mcp.apify.com`. The legacy SSE transport at `https://mcp.apify.com/sse` is deprecated and will be removed in the future. - -::: - -You can interact with the server through legacy Server-Sent Events (SSE) to send messages and receive responses. - -In the client settings, you need to provide server configuration: +For Claude Desktop, add this to your configuration file: ```json { - "mcpServers": { - "apify": { - "type": "sse", - "url": "https://mcp.apify.com/sse", - "headers": { - "Authorization": "Bearer your-apify-token" - } - } + "mcpServers": { + "actors-mcp-server": { + "command": "npx", + "args": ["-y", "@apify/actors-mcp-server"], + "env": { + "APIFY_TOKEN": "YOUR_APIFY_TOKEN" + } } + } } ``` -## Tools, resources, and prompts - -The MCP server provides a set of tools for interacting with Apify Actors. -Since the Apify Store is large and growing rapidly, the MCP server provides a way to dynamically discover and use new Actors. - -### Actors - -Any [Apify Actor](https://apify.com/store) can be used as a tool. -By default, the server is pre-configured with one Actor, `apify/rag-web-browser`, and several helper tools. -The MCP server loads an Actor's input schema and creates a corresponding MCP tool. -This allows the AI agent to know exactly what arguments to pass to the Actor and what to expect in return. - -For example, for the `apify/rag-web-browser` Actor, the input parameters are: +The server will download automatically on first use and connect using your API token. To access Claude's configuration, open the settings and navigate to +the Developer section. -```json -{ - "query": "restaurants in San Francisco", - "maxResults": 3 -} -``` +## Tool selection -You don't need to manually specify which Actor to call or its input parameters; the LLM handles this automatically. -When a tool is called, the arguments are automatically passed to the Actor by the LLM. -You can refer to the specific Actor's documentation for a list of available arguments. +By default, the MCP server loads essential tools for Actor discovery, documentation search, and the RAG Web Browser Actor. You can customize which tools +are available by adding parameters to the server URL: -### Helper tools +`https://mcp.apify.com?tools=actors,docs,apify/web-scraper` -One of the most powerful features of using MCP with Apify is dynamic tool discovery. -It gives an AI agent the ability to find new tools (Actors) as needed and incorporate them. -Here are some special MCP operations and how the Apify MCP Server supports them: +For minimal setups where you only need specific Actors: -- **Apify Actors**: Search for Actors, view their details, and use them as tools for the AI. -- **Apify documentation**: Search the Apify documentation and fetch specific documents to provide context to the AI. -- **Actor runs**: Get lists of your Actor runs, inspect their details, and retrieve logs. -- **Apify storage**: Access data from your datasets and key-value stores. +`https://mcp.apify.com?tools=apify/instagram-scraper,apify/google-search-scraper` -### Overview of available tools +This configuration approach works for both hosted and local setups. For the CLI version: -Here is an overview list of all the tools provided by the Apify MCP Server. - -| Tool name | Category | Enabled by default | Description | -| :--- | :--- | :--- | :---: | -| `search-actors` | actors | ✅ | Search for Actors in the Apify Store. | -| `fetch-actor-details` | actors | ✅ | Retrieve detailed information about a specific Actor. | -| `call-actor` | actors | ✅ | Call an Actor and get its run results. | -| [`apify-slash-rag-web-browser`](https://apify.com/apify/rag-web-browser) | Actor (see [tool configuration](#tools-configuration)) | ✅ | An Actor tool to browse the web. | -| `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-log` | runs | | Retrieve the logs for a specific 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. | -| `add-actor` | experimental | | Add an Actor as a new tool for the user to call. | - -### Tools configuration - -The `tools` configuration parameter is used to specify loaded tools - either categories or specific tools directly, and Apify Actors. For example, `tools=storage,runs` loads two categories; `tools=add-actor` loads just one tool. - -When no query parameters are provided, the MCP server loads the following `tools` by default: - -- `actors` -- `docs` -- `apify/rag-web-browser` - -If the tools parameter is specified, only the listed tools or categories will be enabled - no default tools will be included. +`npx @apify/actors-mcp-server --tools actors,docs,apify/web-scraper` :::tip Easy configuration -Use the [UI configurator](https://mcp.apify.com/) to configure your server, then copy the configuration to your client. +Use the UI configurator `https://mcp.apify.com/` to select your tools visually, then copy the configuration to your client. ::: -#### Configuring the hosted server +### Dynamic tool discovery -The hosted server can be configured using query parameters in the URL. For example, to load the default tools, use: +One of the most powerful features is the ability to discover and use new Actors on demand. It can search Apify Store for relevant Actors using the `search-actors tool`, inspect Actor details to understand required inputs, add the Actor as a new tool, and execute it with appropriate parameters. -```text -https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser -``` +This dynamic discovery means your AI can adapt to new tasks without manual configuration. Each discovered Actor becomes immediately available for future use in the conversation. -For minimal configuration, if you want to use only a single Actor tool - without any discovery or generic calling tools, the server can be configured as follows: +### Available tools -```text -https://mcp.apify.com?tools=apify/my-actor -``` - -This setup exposes only the specified Actor (`apify/my-actor`) as a tool. No other tools will be available. - -#### Configuring the CLI - -The CLI can be configured using command-line flags. For example, to load the same tools as in the hosted server configuration, use: - -```bash -npx @apify/actors-mcp-server --tools actors,docs,apify/rag-web-browser -``` - -The minimal configuration is similar to the hosted server configuration: - -```bash -npx @apify/actors-mcp-server --tools apify/my-actor -``` - -As above, this exposes only the specified Actor (`apify/my-actor`) as a tool. No other tools will be available. - -:::caution Important recommendation +| Tool name | Category | Enabled by default | Description | +| :--- | :--- | :--- | :--- | +| `search-actors` | actors | ✅ | Search for Actors in Apify Store | +| `fetch-actor-details` | actors | ✅ | Retrieve detailed information about a specific Actor | +| `call-actor` | actors | ✅ | Call an Actor and get its run results | +| [`apify/rag-web-browser`](https://apify.com/apify/rag-web-browser) | Actor | ✅ | Browse and extract web data | +| `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-log` | runs | | Retrieve the logs for a specific 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 | +| `add-actor` | experimental | | Add an Actor as a new tool for the user to call | -_The default tools configuration may change in future versions._ When no `tools` parameter is specified, the server currently loads default tools, but this behavior is subject to change. +## Advanced usage -_For production use and stable interfaces, always explicitly specify the `tools` parameter_ to ensure your configuration remains consistent across updates. +### Production best practices -::: +For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates: -### Prompts +`npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` -The server provides a set of predefined example prompts to help you get started interacting with Apify through MCP. For example, there is a `GetLatestNewsOnTopic` prompt that allows you to easily retrieve the latest news on a specific topic using the [RAG Web Browser](https://apify.com/apify/rag-web-browser) Actor. +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. -### Resources +### Rate limits and performance -The server does not yet provide any resources. +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. -## Rate limits +For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results. -The Apify MCP server has a rate limit of _30 requests per second_ per user. If you exceed this limit, you will receive a `429 Too Many Requests` response. +## Support and resources -## Support and contribution +The Apify MCP Server is an open-source project. Report bugs, suggest features, or ask questions in the [GitHub repository](https://github.com/apify/actors-mcp-server/issues). -The Apify MCP Server is an open-source project. -You can report bugs, suggest new features, or ask questions in the [GitHub issues](https://github.com/apify/actors-mcp-server/issues). -If you find this project useful, please [star it on GitHub](https://github.com/apify/actors-mcp-server) to show your support! +If you find this project useful, please star it on [GitHub](https://github.com/apify/actors-mcp-server) to show your support! -- _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. -- _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. -- _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+. -- _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. +To learn more about MCP and Apify integration: -## Learn more +- [Model Context Protocol specification](https://modelcontextprotocol.io) - 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](https://blog.apify.com/how-to-use-mcp/) - Learn how to expose over thousands of Apify Actors to AI agents with Claude and LangGraph, and configure MCP clients and servers. +- [Video tutorial](https://www.youtube.com/watch?v=BKu8H91uCTg) - Integrate thousands of Apify Actors and Agents with Claude. +- [Apify Tester MCP Client](https://apify.com/jiri.spilka/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. -- [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. -- [Actors MCP Server GitHub](https://github.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. -- [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. -- [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. -- [Apify MCP Server Tutorial](https://www.youtube.com/watch?v=BKu8H91uCTg): Integrate thousands of Apify Actors and Agents with Claude. From 68d98c36e18d00a484a95d87aca3a0045b51dab8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 15 Sep 2025 22:57:25 +0200 Subject: [PATCH 02/10] add troubleshooting section --- sources/platform/integrations/ai/mcp.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 8e5b402416..64539871aa 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -167,6 +167,24 @@ documentation queries. If you exceed this limit, you'll receive a `429` response For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results. +## Troubleshooting + +This section covers common issues you might encounter while using the Apify MCP server. + +### Authentication errors + +- _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). 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](https://github.com/apify/actors-mcp-server/issues). From f8d417e474e6cb8b6d501354592738e0f67f2af2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 15 Sep 2025 23:08:27 +0200 Subject: [PATCH 03/10] slight adjustments to H2 paragraphs --- sources/platform/integrations/ai/mcp.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 64539871aa..e7995e32d5 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -25,7 +25,7 @@ Before connecting your AI to Apify, you'll need three things: ## Quick start -To get started with the Apify MCP server you have two options. +You can connect to the Apify MCP server in two ways: use our hosted service for a quick and easy setup, or run the server locally for development and testing. ### Streamable HTTP with OAuth (recommended) @@ -154,23 +154,21 @@ This dynamic discovery means your AI can adapt to new tasks without manual confi ### Production best practices -For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates: +- For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates: -`npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` + `npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` -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. +- 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. +- For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results. -### Rate limits and performance +## 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. -For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results. - ## Troubleshooting -This section covers common issues you might encounter while using the Apify MCP server. - ### Authentication errors - _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). Without a valid token, the server cannot start Actor runs. From 796dca2083621ef7a2710087ea27f54e4226c360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 15 Sep 2025 23:22:37 +0200 Subject: [PATCH 04/10] change headings in troubleshooting section and add mdlint rule disable --- sources/platform/integrations/ai/mcp.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index e7995e32d5..57e09e9173 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -167,22 +167,24 @@ This dynamic discovery means your AI can adapt to new tasks without manual confi 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 -### Authentication errors +#### Authentication errors - _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). 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 +#### 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 +#### 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](https://github.com/apify/actors-mcp-server/issues). From ff851083d6bd7b049da7573983beecb93f0c1b45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 15 Sep 2025 23:27:44 +0200 Subject: [PATCH 05/10] fix typo --- sources/platform/integrations/ai/mcp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 57e09e9173..23c2ac8503 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -123,7 +123,7 @@ Use the UI configurator `https://mcp.apify.com/` to select your tools visually, ### Dynamic tool discovery -One of the most powerful features is the ability to discover and use new Actors on demand. It can search Apify Store for relevant Actors using the `search-actors tool`, inspect Actor details to understand required inputs, add the Actor as a new tool, and execute it with appropriate parameters. +One of the most powerful features is the ability to discover and use new Actors on demand. It can search Apify Store for relevant Actors using the `search-actors` tool, inspect Actor details to understand required inputs, add the Actor as a new tool, and execute it with appropriate parameters. This dynamic discovery means your AI can adapt to new tasks without manual configuration. Each discovered Actor becomes immediately available for future use in the conversation. From cd071cadfb4f167acd08235de03c051b0c66fa26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 16 Sep 2025 17:59:55 +0200 Subject: [PATCH 06/10] add new section about MCP configuration for popular tools --- sources/platform/integrations/ai/mcp.md | 170 +++++++++++++++++++++--- 1 file changed, 150 insertions(+), 20 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 23c2ac8503..b8fc4b1640 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -4,6 +4,7 @@ sidebar_label: MCP description: Learn how to use the Apify MCP server to integrate Apify's library of Actors into your AI agents or large language model-based applications. sidebar_position: 1 slug: /integrations/mcp +toc_max_heading_level: 4 --- @@ -38,13 +39,12 @@ When you connect for the first time, you'll be redirected to your browser to sig authentication without exposing your API token. ```json - { -"mcpServers": { + "mcpServers": { "apify": { - "url": "https://mcp.apify.com" + "url": "https://mcp.apify.com" } -} + } } ``` @@ -55,17 +55,19 @@ You can also use your Apify token directly, instead of OAuth, by setting the `Au ```json { -"mcpServers": { -"apify": { - "url": "https://mcp.apify.com", - "headers": { - "Authorization": "Bearer your-apify-token" + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer " + } } -} -} + } } ``` +Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). + @@ -73,15 +75,145 @@ You can also use your Apify token directly, instead of OAuth, by setting the `Au _MCP server configuration for other clients_: Use the [UI configuration tool](https://mcp.apify.com/) to select Actors and tools, then copy the configuration to your client. -_Claude Desktop_: Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation. +::: + +#### Text editor configuration + +Here's how to add the Apify MCP server to popular text editors and AI assistants: + + + + +To add Apify MCP server to Cursor: + +1. Create or open the `.cursor/mcp.json` file. +1. Add the following to the configuration file: + + + + + ```json + { + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } + } + } + ``` + + When you connect for the first time, you'll be redirected to your browser to sign in to Apify and authorize the connection. This OAuth flow ensures secure authentication without exposing your API token. + + + + + You can also use your Apify token directly, instead of OAuth, by setting the `Authorization: Bearer ` header in the MCP server configuration. + + ```json + { + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). + + + + + + + +VS Code supports MCP through GitHub Copilot's agent mode(requires Copilot subscription): + +1. Ensure you have GitHub Copilot installed +1. 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. +1. Add the following to the configuration file: + + + + + ```json + { + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } + } + } + ``` + + When you connect for the first time, you'll be redirected to your browser to sign in to Apify and authorize the connection. This OAuth flow ensures secure authentication without exposing your API token. + + + + + You can also use your Apify token directly, instead of OAuth, by setting the `Authorization: Bearer ` header in the MCP server configuration. + + ```json + { + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). + + + + + + + +:::tip One-click installation + +Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation. ::: +To manually configure Apify's MCP server for Claude Desktop: + +1. Open Claude Desktop settings. +1. Navigate to the **Developer** section. +1. Add the following to the configuration file: + +```json +{ + "mcpServers": { + "actors-mcp-server": { + "command": "npx", + "args": ["-y", "@apify/actors-mcp-server"], + "env": { + "APIFY_TOKEN": "" + } + } + } +} +``` + +Replace `` with your actual Apify API token from the [Integrations section](https://console.apify.com/account#/integrations). + + + + ### Local stdio -For development environments or Claude Desktop, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing. +For development environments, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing. -For Claude Desktop, add this to your configuration file: +Add this to your configuration file: ```json { @@ -97,8 +229,7 @@ For Claude Desktop, add this to your configuration file: } ``` -The server will download automatically on first use and connect using your API token. To access Claude's configuration, open the settings and navigate to -the Developer section. +The server will download automatically on first use and connect using your API token. ## Tool selection @@ -170,17 +301,17 @@ documentation queries. If you exceed this limit, you'll receive a `429` response ## Troubleshooting -#### Authentication errors +##### Authentication errors - _Check your API token_: Verify that your Apify API token is correct. You can find it in the **Integrations** section of the [Apify Console](https://console.apify.com/account#/integrations). 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 +##### 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 +##### 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. @@ -197,4 +328,3 @@ To learn more about MCP and Apify integration: - [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/) - Learn how to expose over thousands of Apify Actors to AI agents with Claude and LangGraph, and configure MCP clients and servers. - [Video tutorial](https://www.youtube.com/watch?v=BKu8H91uCTg) - Integrate thousands of Apify Actors and Agents with Claude. - [Apify Tester MCP Client](https://apify.com/jiri.spilka/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. - From b7d83fefc3aa1384669c77fe78d92bf34b678783 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Thu, 18 Sep 2025 11:07:01 +0200 Subject: [PATCH 07/10] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jakub Kopecký --- sources/platform/integrations/ai/mcp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index b8fc4b1640..0679f13081 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -318,9 +318,9 @@ documentation queries. If you exceed this limit, you'll receive a `429` response ## Support and resources -The Apify MCP Server is an open-source project. Report bugs, suggest features, or ask questions in the [GitHub repository](https://github.com/apify/actors-mcp-server/issues). +The Apify MCP Server is an open-source project. Report bugs, suggest features, or ask questions in the [GitHub repository](https://github.com/apify/apify-mcp-server/issues). -If you find this project useful, please star it on [GitHub](https://github.com/apify/actors-mcp-server) to show your support! +If you find this project useful, please star it on [GitHub](https://github.com/apify/apify-mcp-server) to show your support! To learn more about MCP and Apify integration: From 5800b41cb0fa0b6491304edc02d3f89fcbd99caa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 30 Sep 2025 23:47:12 +0200 Subject: [PATCH 08/10] address doc review --- sources/platform/integrations/ai/mcp.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 0679f13081..b8b96358db 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -26,7 +26,7 @@ Before connecting your AI to Apify, you'll need three things: ## Quick start -You can connect to the Apify MCP server in two ways: use our hosted service for a quick and easy setup, or run the server locally for development and testing. +You can connect to the Apify MCP server in two ways: use our hosted service for a quick and easy setup using [Streamable HTTP with OAuth](#streamable-http-with-oauth-recommended), or run the server locally for development and testing using [local stdio](#local-stdio). ### Streamable HTTP with OAuth (recommended) @@ -77,7 +77,7 @@ _MCP server configuration for other clients_: Use the [UI configuration tool](ht ::: -#### Text editor configuration +#### Client configuration Here's how to add the Apify MCP server to popular text editors and AI assistants: @@ -211,7 +211,7 @@ Replace `` with your actual Apify API token from the [Integrations ### Local stdio -For development environments, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing. +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: @@ -291,7 +291,6 @@ This dynamic discovery means your AI can adapt to new tasks without manual confi - 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. -- For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results. ## Rate limits and performance From 5932f6cb644fa34491ba223651dc9d661efb4973 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Tue, 30 Sep 2025 23:52:42 +0200 Subject: [PATCH 09/10] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jiří Spilka --- sources/platform/integrations/ai/mcp.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index b8b96358db..20ea6e3914 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -236,7 +236,7 @@ The server will download automatically on first use and connect using your API t By default, the MCP server loads essential tools for Actor discovery, documentation search, and the RAG Web Browser Actor. You can customize which tools are available by adding parameters to the server URL: -`https://mcp.apify.com?tools=actors,docs,apify/web-scraper` +`https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser` For minimal setups where you only need specific Actors: @@ -287,9 +287,9 @@ This dynamic discovery means your AI can adapt to new tasks without manual confi - For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates: - `npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` + `https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser` -- Always use the latest version of the server by appending `@latest` to your npm commands. +- 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 From 71640cec16c83dc1f400dd82fdfdfa317539a21a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Kopeck=C3=BD?= Date: Wed, 1 Oct 2025 10:11:17 +0200 Subject: [PATCH 10/10] docs: add get-actor-output tool (#1932) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add `get-actor-output` tools info and merge into the https://github.com/apify/apify-docs/pull/1927 --- > [!NOTE] > Documents a new `get-actor-output` tool for retrieving full Actor outputs, with a note on automatic inclusion, datasetId usage, and pagination/field filtering. > > - **Docs (MCP server)**: > - **New tool**: Add `get-actor-output` entry to the Available tools table. > - **Usage note**: Explain that it’s auto-included with Actor tools (e.g., `call-actor`, `add-actor`), used to fetch full output via `datasetId`, and supports limit/offset/field filtering. > > Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit a46162bf86e47e0730e07a24c839ce160d983288. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot). --------- Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> --- sources/platform/integrations/ai/mcp.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 20ea6e3914..2f1f9cd64e 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -280,6 +280,13 @@ This dynamic discovery means your AI can adapt to new tasks without manual confi | `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 | | `add-actor` | experimental | | Add an Actor as a new tool for the user to call | +| `get-actor-output`* | - | Retrieve the output from an Actor call which is not included in the output preview of the Actor tool. | ✅ | + +:::note Retrieving full output + +The `get-actor-output` tool is automatically included with any Actor-related tool, such as `call-actor`, `add-actor`, or specific Actor tools like `apify-slash-rag-web-browser`. When you call an Actor, you receive an output preview. Depending on the output format and length, the preview may contain the complete output or only a limited version to avoid overwhelming the LLM. To retrieve the full output, use the `get-actor-output` tool with the `datasetId` from the Actor call. This tool supports limit, offset, and field filtering. + +::: ## Advanced usage