From b17be740c1673aceec45ab5687e3e09429309d2a Mon Sep 17 00:00:00 2001 From: MQ Date: Tue, 26 Aug 2025 13:26:39 +0200 Subject: [PATCH 1/4] docs(mcp): update to reflect the new configuration spec --- sources/platform/integrations/ai/mcp.md | 177 +++++++++++++++--------- 1 file changed, 114 insertions(+), 63 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 0a8b95fc8..f4b5ffa63 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -53,6 +53,21 @@ During setup, provide the server URL `https://mcp.apify.com`. You will then be r } ``` +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" + } + } + } +} +``` + ## Example usage (local stdio with Claude for Desktop) Let’s walk through an example of using Claude for Desktop with the Apify MCP Server: @@ -87,9 +102,15 @@ If you prefer not to set up Claude desktop, you can achieve a similar result usi ![Apify Tester MCP Client](../../images/chat-ui.webp) -## Interact with the MCP server over SSE +## Interact with the MCP server over legacy SSE transport -You can interact with the server through Server-Sent Events (SSE) to send messages and receive responses. +:::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 via `https://mcp.apify.com` instead of `https://mcp.apify.com/sse`. The legacy SSE transport 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: @@ -107,102 +128,132 @@ In the client settings, you need to provide server configuration: } ``` -## Adding Multiple Actors +## 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. -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: +### Actors -- _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. - _Tools for adding and removing Actors are enabled by default._ - You can disable these tools by setting the parameter `?enableAddingActors=false` in the MCP Server URL, or with the CLI flag `--enable-adding-actors=false` (can also be set in Claude for Desktop config args as `--enable-adding-actors=false`). - Not all MCP client frameworks allow dynamic tool addition at runtime, but Apify’s own tester client does, if adding Actors is enabled. -- _Via url:_ If you are using Streamable HTTP or SSE protocol, you could add `actors` query parameter with Actor names separated by comma: +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: ```json { - "mcpServers": { - "Apify": { - "url": "https://mcp.apify.com/?actors=lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper" - } - } + "query": "restaurants in San Francisco", + "maxResults": 3 } ``` -- _Via config file:_ For local stdio connection, you can specify which Actors should be immediately available by configuring your json configuration. 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. +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. -```json - { - "mcpServers": { - "actors-mcp-server": { - "command": "npx", - "args": [ - "-y", "@apify/actors-mcp-server", - "--actors", "lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper" - ], - "env": { - "APIFY_TOKEN": "YOUR_APIFY_TOKEN" - } - } - } - } -``` +### Helper tools + +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: + +- **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. +### Overview of available tools -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. +Here is an overview list of all the tools provided by the Apify MCP Server. -## Configure tools for the MCP server +| Tool name | Category | Description | Enabled by default | +| :--- | :--- | :--- | :---: | +| `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. | | -You can customize the MCP server’s available tools by adding query parameters to the server URL or by passing arguments to the CLI. -This allows you to enable or disable specific tool categories and control which tools are available. +### Tools configuration -The following tool categories are available: +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. -- _Actor discovery and management_ (default, always enabled): Search for [Actors](https://docs.apify.com/platform/actors) (`search-actors`), view details (`get-actor-details`), and dynamically add them (`add-actor`). -- _docs_ (default, can be disabled): Search Apify documentation (`search-apify-docs`) and fetch specific documents (`fetch-apify-docs`). -- _runs_ (optional): Get a list of your [Actor runs](https://docs.apify.com/platform/actors/running/runs-and-builds#runs) (`get-actor-run-list`), specific run details (`get-actor-run`), and logs from a specific Actor run (`get-actor-log`). -- _storage_ (optional): Access [datasets](https://docs.apify.com/platform/storage/dataset) and [key-value stores](https://docs.apify.com/platform/storage/key-value-store), including their records (`get-dataset`, `get-dataset-items`, `get-dataset-list`, `get-key-value-store`, `get-key-value-store-keys`, `get-key-value-store-record`, `get-key-value-store-records`). -- _preview_ (optional): Experimental tools in preview mode. Call any Actor using API (`call-actor`). +When no query parameters are provided, the MCP server loads the following `tools` by default: -The _Actor discovery and management_ tools are always present and cannot be disabled. -The _docs_ tools are enabled by default but can be switched off using the `tools` parameter. +- `actors` +- `docs` +- `apify/rag-web-browser` -### Configure mcp.apify.com using query parameters +If the tools parameter is specified, only the listed tools or categories will be enabled - no default tools will be included. -Use the `tools` query parameter to enable or disable specific tool categories. +:::tip Easy configuration -For example, to enable only the `runs` and `storage` tools, you can use: +Use the [UI configurator](https://mcp.apify.com/) to configure your server, then copy the configuration to your client. + +::: + +**Configuring the hosted server:** + +The hosted server can be configured using query parameters in the URL. For example, to load the default tools, use: ```text -https://mcp.apify.com/?tools=runs,storage +https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser ``` -The server will expose all _Actor discovery and management tools_, as well as `runs` and `storage`. -The list of tools you can enable/disable is as follows: `docs`, `runs`, `storage`, and `preview`. +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: +```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:** -### Configure stdio server using CLI arguments +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 +``` -When running the MCP server via the command line, you can specify the tools using the `--tools` parameter. -For example, to enable only the `runs` and `storage` tools, you can run: +The minimal configuration is similar to the hosted server configuration: ```bash -npx @apify/actors-mcp-server --tools runs,storage +npx @apify/actors-mcp-server --tools apify/my-actor ``` -## Dynamic discovery of Actors +As above, this exposes only the specified Actor (`apify/my-actor`) as a tool. No other tools will be available. + +:::caution Important recommendation + +**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. -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. +**For production use and stable interfaces, always explicitly specify the `tools` parameter** to ensure your configuration remains consistent across updates. + +::: -Supported dynamic tool operations (enabled by default): +### Prompts -- `search-actors`: Find available Actors by keyword or category. -- `get-actor-details`: View details and usage information for a specific Actor. -- `add-actor`: Dynamically add an Actor as a tool for the current session, making it available for use. +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. -These operations allow your agent to expand its toolset on demand, without requiring a server restart or manual configuration. +### Resources -Dynamic tool addition can be disabled using the `?enableAddingActors=false`. -Not all MCP clients support dynamic tool addition. -Check your client’s documentation or settings to confirm this feature is available. +The server does not yet provide any resources. ## Rate limits From 5b5fe5b28bbf82b3ad4bbf870e46fb20c4933f57 Mon Sep 17 00:00:00 2001 From: MQ Date: Tue, 26 Aug 2025 13:47:47 +0200 Subject: [PATCH 2/4] make the legacy sse caution more explicit --- 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 f4b5ffa63..4938c3569 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -106,7 +106,7 @@ If you prefer not to set up Claude desktop, you can achieve a similar result usi :::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 via `https://mcp.apify.com` instead of `https://mcp.apify.com/sse`. The legacy SSE transport is deprecated and will be removed in the future. +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. ::: From 9c838341d981f812c4b9d5a98768c760aa93592b Mon Sep 17 00:00:00 2001 From: MQ Date: Wed, 27 Aug 2025 15:33:25 +0200 Subject: [PATCH 3/4] reoder table cols, address comments --- sources/platform/integrations/ai/mcp.md | 46 ++++++++++++------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/sources/platform/integrations/ai/mcp.md b/sources/platform/integrations/ai/mcp.md index 4938c3569..9f98f8548 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -168,26 +168,26 @@ Here are some special MCP operations and how the Apify MCP Server supports them: Here is an overview list of all the tools provided by the Apify MCP Server. -| Tool name | Category | Description | Enabled by default | +| 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. | | +| `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 @@ -207,7 +207,7 @@ Use the [UI configurator](https://mcp.apify.com/) to configure your server, then ::: -**Configuring the hosted server:** +#### Configuring the hosted server The hosted server can be configured using query parameters in the URL. For example, to load the default tools, use: @@ -223,7 +223,7 @@ 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:** +#### 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: @@ -241,9 +241,9 @@ As above, this exposes only the specified Actor (`apify/my-actor`) as a tool. No :::caution Important recommendation -**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. +_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. -**For production use and stable interfaces, always explicitly specify the `tools` parameter** to ensure your configuration remains consistent across updates. +_For production use and stable interfaces, always explicitly specify the `tools` parameter_ to ensure your configuration remains consistent across updates. ::: From da5f79e3abc37750ee6ad42693d43aceaf4bed3b Mon Sep 17 00:00:00 2001 From: MQ Date: Wed, 27 Aug 2025 15:39:55 +0200 Subject: [PATCH 4/4] update dxt link - we will change it in the repo --- 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 9f98f8548..e90ef89ab 100644 --- a/sources/platform/integrations/ai/mcp.md +++ b/sources/platform/integrations/ai/mcp.md @@ -25,7 +25,7 @@ You can use the Apify MCP Server in two ways: :::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. -_Claude Desktop_: Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/actors-mcp-server.dxt) for one-click installation. +_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. :::