From ad965ce01142883cb1fcd8b2c26a56590f4bbf62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 25 May 2026 17:20:38 +0200 Subject: [PATCH 1/3] docs: add MCP Connectors documentation Introduces sources/platform/integrations/ai/mcp-connectors/ with the feature landing page and Actor-developer guide. Extends the input schema spec with the mcpConnector resourceType, adds APIFY_MCP_PROXY_URL to environment variables, and documents Connector management under console settings. Cross-links related AI pages and adds Connector capitalization to the terminology standards. --- .../input_schema/secret_input.md | 6 + .../input_schema/specification.md | 65 ++- .../environment_variables.md | 1 + .../quick-start/develop_ai_agents.md | 4 + sources/platform/console/settings.md | 54 +++ .../integrations/ai/agent-onboarding.md | 1 + .../integrations/ai/mcp-connectors/index.md | 87 ++++ .../using-connectors-in-actors.md | 455 ++++++++++++++++++ sources/platform/integrations/ai/mcp/index.md | 6 + sources/platform/integrations/index.mdx | 7 + standards/terminology.md | 10 + 11 files changed, 678 insertions(+), 18 deletions(-) create mode 100644 sources/platform/integrations/ai/mcp-connectors/index.md create mode 100644 sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md diff --git a/sources/platform/actors/development/actor_definition/input_schema/secret_input.md b/sources/platform/actors/development/actor_definition/input_schema/secret_input.md index 8b84b81c10..61cdb40709 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/secret_input.md +++ b/sources/platform/actors/development/actor_definition/input_schema/secret_input.md @@ -7,6 +7,12 @@ slug: /actors/development/actor-definition/input-schema/secret-input The secret input feature lets you mark specific input fields of an Actor as sensitive. When you save the Actor's input configuration, the values of these marked fields get encrypted. The encrypted input data can only be decrypted within the Actor. This provides an extra layer of security for sensitive information like API keys, passwords, or other confidential data. +:::tip MCP Connectors for third-party credentials + +If the third-party service you need exposes a [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server, consider using [MCP Connectors](/platform/integrations/mcp-connectors) instead. The user authorizes the service once in their account settings, and the Actor receives a Connector ID rather than a credential - the token itself never enters the Actor. For credentials without an MCP server (database passwords, generic API keys), continue to use `isSecret: true`. + +::: + ## How to set a secret input field To make an input field secret, you need to add a `"isSecret": true` setting to the input field in the Actor's [input schema](./index.md), like this: diff --git a/sources/platform/actors/development/actor_definition/input_schema/specification.md b/sources/platform/actors/development/actor_definition/input_schema/specification.md index 81eda1a39b..c79eecf529 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/specification.md +++ b/sources/platform/actors/development/actor_definition/input_schema/specification.md @@ -889,7 +889,8 @@ As with objects, the sub-schema feature for arrays only works for level 1 sub-pr ### Resource type Resource type identifies what kind of Apify Platform object is referred to in the input field. For example, the Key-value store resource type can be referred to using a string ID. -Currently, it supports storage resources only, allowing the reference of a Dataset, Key-Value Store or Request Queue. + +Supported resource types are storage resources (dataset, key-value store, request queue) and [MCP Connectors](/platform/integrations/mcp-connectors), which let an Actor call third-party MCP servers using credentials the user has authorized in their account. For Actor developers, the resource input value is a string representing either the resource ID or (unique) name. The type of the property is either `string` or `array`. In case of `array` (for multiple resources) the return value is an array of IDs or names. @@ -932,26 +933,26 @@ Rendered input: #### Single value properties -| Property | Value | Required | Description | -|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------| -| `type` | `string` | Yes | Specifies the type of input - `string` for single value. | -| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | -| `resourceType` | One of | Yes | Type of Apify Platform resource | -| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resource. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. | -| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. | -| `minLength` | Integer | No | Minimum length of the string. | -| `maxLength` | Integer | No | Maximum length of the string. | +| Property | Value | Required | Description | +| --- | --- | --- | --- | +| `type` | `string` | Yes | Specifies the type of input - `string` for single value. | +| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | +| `resourceType` | One of | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept an [MCP Connector](/platform/integrations/mcp-connectors) as input. | +| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | Permissions requested for the referenced resource. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. | +| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. | +| `minLength` | Integer | No | Minimum length of the string. | +| `maxLength` | Integer | No | Maximum length of the string. | #### Multiple values properties -| Property | Value | Required | Description | -|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. | -| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | -| `resourceType` | One of | Yes | Type of Apify Platform resource | -| `resourcePermissions` | Array of strings; allowed values: | Yes | Permissions requested for the referenced resources. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. Applies to each selected resource. | -| `minItems` | Integer | No | Minimum number of items the array can contain. | -| `maxItems` | Integer | No | Maximum number of items the array can contain. | +| Property | Value | Required | Description | +| --- | --- | --- | --- | +| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. | +| `editor` | One of | No | Visual editor used for
the input field. Defaults to `resourcePicker`. | +| `resourceType` | One of | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept [MCP Connectors](/platform/integrations/mcp-connectors) as input. | +| `resourcePermissions` | Array of strings; allowed values: | Yes for storage resources; not used for `mcpConnector` | Permissions requested for the referenced resources. Use [\"READ\"] for read-only access, or [\"READ\", \"WRITE\"] to allow writes. Applies to each selected resource. | +| `minItems` | Integer | No | Minimum number of items the array can contain. | +| `maxItems` | Integer | No | Maximum number of items the array can contain. | #### Resource permissions @@ -966,6 +967,34 @@ This setting defines runtime access only and doesn't change field visibility or ::: +#### MCP Connector resource type + +When `resourceType` is `mcpConnector`, the input field accepts one or more [MCP Connectors](/platform/integrations/mcp-connectors) the user has authorized in their account. The Actor receives the Connector ID (or an array of IDs) as the input value and connects to the upstream MCP server through the Apify MCP Proxy at runtime. + +The `mcpConnector` resource type does not use `resourcePermissions`. Instead, eligibility and per-tool access are declared through a required `mcpServers` field, which lists the upstream MCP server URLs and tool constraints the Actor accepts: + +```json +{ + "slackConnector": { + "title": "Slack Connector", + "description": "Read-only access to your Slack workspace", + "type": "string", + "resourceType": "mcpConnector", + "mcpServers": [ + { + "url": "https://mcp.slack.com/mcp", + "tools": { + "required": ["list_*", "get_*", "read_*"], + "readOnly": true + } + } + ] + } +} +``` + +The same declaration acts as both eligibility filter (the input picker only offers compatible Connectors) and runtime ceiling (the proxy rejects tool calls outside the declared set). For the full `mcpServers` schema, behavioral hints, and code samples, see [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors). + ### Deprecation of `patternKey` and `patternValue` ::::warning Deprecation notice diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index ff193b16f2..8a1e2e4598 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -66,6 +66,7 @@ System variables apply only to Actor runs and are never passed to builds - not e | `APIFY_META_ORIGIN` | Specifies how an Actor run was started. Possible values are in [Runs and builds](/platform/actors/running/runs-and-builds#origin) documentation. | | `APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE` | Path to the secret key used to decrypt [Secret inputs](/platform/actors/development/actor-definition/input-schema/secret-input). | | `APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE` | Passphrase for the input secret key specified in `APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE`. | +| `APIFY_MCP_PROXY_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP Connector](/platform/integrations/mcp-connectors) at `${APIFY_MCP_PROXY_URL}/` using `APIFY_TOKEN` as the bearer token. | diff --git a/sources/platform/actors/development/quick-start/develop_ai_agents.md b/sources/platform/actors/development/quick-start/develop_ai_agents.md index 5cf707ab63..656a6546a9 100644 --- a/sources/platform/actors/development/quick-start/develop_ai_agents.md +++ b/sources/platform/actors/development/quick-start/develop_ai_agents.md @@ -78,6 +78,10 @@ AI Sandbox runs on a Debian image with Node.js version 24 and Python 3.11 pre-in ::: +## Connect to user services with MCP Connectors + +If your agent needs to act on a user's third-party accounts - posting to Slack, writing to Notion, querying GitHub - use [MCP Connectors](/platform/integrations/mcp-connectors). The user authorizes each service once in their account settings, and your Actor receives a Connector ID as input. The token itself never enters the Actor: the Apify MCP Proxy injects credentials server-side at runtime. Declare which services your Actor accepts in the input schema with `resourceType: "mcpConnector"`. See [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors) for the full schema and code samples. + ## Access LLMs with OpenRouter The [OpenRouter](https://apify.com/apify/openrouter) Actor provides access to 100+ LLMs through your Apify account. Supported providers include OpenAI, Anthropic, Google, Mistral, Meta, and more. No separate API keys or billing setup required - all costs are billed as platform usage. diff --git a/sources/platform/console/settings.md b/sources/platform/console/settings.md index 66652dea21..175284fb53 100644 --- a/sources/platform/console/settings.md +++ b/sources/platform/console/settings.md @@ -38,6 +38,60 @@ In the **Session information** section, you can adjust the session configuration The **API & Integrations** tab provides essential tools for accessing the Apify platform programmatically. Here, you can manage your **API tokens**, which are necessary for using the [Apify API](https://docs.apify.com/api/v2). The tab also shows **third-party apps and services** connected to your account, **account-level integrations**, and **Actor OAuth accounts**. For detailed guidance on utilizing these integrations, refer to the [Integrations documentation](https://docs.apify.com/platform/integrations). +### MCP Connectors + +The **MCP Connectors** section lets you authorize third-party MCP servers (such as Notion, Slack, GitHub, or Supabase) once and reuse those connections across any Actor that accepts them. For an overview of the feature, see [MCP Connectors](/platform/integrations/mcp-connectors). + +#### Create a Connector + +1. Open **Settings > API & Integrations > MCP Connectors** and click **Create new Connector**. +1. Enter the MCP server URL, for example: + + ```text + https://mcp.slack.com/mcp + https://api.notion.com/mcp + https://mcp.sentry.io/mcp + ``` + + The platform inspects the URL and offers the authentication methods the server supports. + +1. Choose an authentication method: + + * _API key or bearer token_ - the MCP server uses a static API key or personal access token. Enter the key. Apify verifies it by connecting to the MCP server. + * _OAuth_ - the server supports OAuth and Apify can either register an OAuth client automatically (Dynamic Client Registration) or use an Apify-managed OAuth client. A consent screen opens in a popup. Grant access and close the popup. + * _Own OAuth client_ - the server supports OAuth but you need to register your own OAuth app with the provider (see below). Enter your client ID, client secret, authorization URL, and token URL, then complete the OAuth consent flow. + +1. Review the discovered tools. Once authorized, the platform connects to the MCP server and discovers the tools it exposes. You can see them by expanding the Connector card. + +#### Set up your own OAuth client + +Most OAuth providers - including GitHub, Slack, Google, and Microsoft Entra - do not currently support Apify's automatic OAuth client setup. For these, register an OAuth app yourself: + +1. Open the provider's developer portal (for example, GitHub **Settings > Developer settings > OAuth Apps**, or [api.slack.com/apps](https://api.slack.com/apps)). +1. Create a new OAuth app. +1. Add the following Apify URL as an authorized redirect or callback URI: + + ```text + https://console.apify.com/oauth/mcp-proxy + ``` + +1. Copy the client ID and client secret. +1. In the Connector creation modal, select **Own OAuth client** and provide: + * Client ID + * Client secret + * Authorization URL (for example, `https://github.com/login/oauth/authorize`) + * Token URL (for example, `https://github.com/login/oauth/access_token`) + +This is the same approach used by Claude Code, VS Code, and ChatGPT integrations. + +#### Reauthorize a Connector + +The platform refreshes OAuth access tokens automatically and transparently. The Actor never needs to handle this. Reauthorization is only needed when the refresh token itself has expired or been revoked, for example if you removed Apify's access from the provider's app settings. In that case, the **Authorize** button appears on the Connector card. Click it to go through the OAuth consent flow again. + +#### Delete a Connector + +Click **Delete** on the Connector card. The Connector is removed immediately and can no longer be used by any Actor. + ## Organizations The **Organizations** tab is where you can view your accounts' current organizations, create new organizations, or convert your user account into an organization account. For more information on how to set up an organization, check out this [article](https://help.apify.com/en/articles/8698948-how-to-set-up-an-organization-account). diff --git a/sources/platform/integrations/ai/agent-onboarding.md b/sources/platform/integrations/ai/agent-onboarding.md index 7048fbd38b..81f94c9f0f 100644 --- a/sources/platform/integrations/ai/agent-onboarding.md +++ b/sources/platform/integrations/ai/agent-onboarding.md @@ -17,6 +17,7 @@ Connect your AI agent or application to Apify - the platform for web scraping, d - _Actors_ - Serverless cloud programs that perform scraping, crawling, or automation tasks. Thousands of ready-made Actors are available in [Apify Store](https://apify.com/store). - _Datasets_ - Append-only storage for structured results. Every Actor run creates a default dataset. Export as JSON, CSV, Excel, XML, or RSS. - _API_ - RESTful API at `https://api.apify.com/v2` for all platform operations. Also accessible via [MCP](/platform/integrations/mcp), [CLI](/cli), and client libraries. +- _MCP Connectors_ - When you build an Actor that needs to act on a user's third-party accounts (Notion, Slack, GitHub, and others), use [MCP Connectors](/platform/integrations/mcp-connectors) to receive Connector IDs as input instead of asking users for raw credentials. ## Prerequisites diff --git a/sources/platform/integrations/ai/mcp-connectors/index.md b/sources/platform/integrations/ai/mcp-connectors/index.md new file mode 100644 index 0000000000..819b89b628 --- /dev/null +++ b/sources/platform/integrations/ai/mcp-connectors/index.md @@ -0,0 +1,87 @@ +--- +title: MCP Connectors +sidebar_label: MCP Connectors +description: Use MCP Connectors to let Apify Actors call third-party services through Model Context Protocol on your behalf, without exposing your credentials to Actor code. +sidebar_position: 0.5 +slug: /integrations/mcp-connectors +--- + +MCP Connectors let Actors call third-party services - Notion, Slack, GitHub, Sentry, Supabase, and others - through [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) on your behalf, using your credentials, without ever exposing those credentials to the Actor code. + +You authorize a Connector once in your account settings. When you run an Actor that accepts Connectors, the input form shows a picker filtered to those compatible with the Actor's requirements. At runtime, the Apify platform injects your credentials server-side. The Actor never sees a token. + +:::info Apify MCP server vs MCP Connectors + +The [Apify MCP server](/platform/integrations/mcp) exposes Apify Actors as tools to outside AI clients (Claude, ChatGPT, Cursor, and others). MCP Connectors do the opposite: they let Apify Actors call external MCP servers as tools. The two features are independent and can be used together or separately. + +::: + +## How it works + +```mermaid +flowchart LR + subgraph actor [Your Actor] + client["MCP client

Reads env vars:
APIFY_MCP_PROXY_URL
APIFY_TOKEN"] + end + + subgraph platform [Apify platform] + proxy["MCP Proxy
• Injects credentials
• Enforces tool policies
• Validates upstream URL"] + end + + external["External service
e.g. Slack MCP"] + + client -- "Bearer APIFY_TOKEN" --> proxy + proxy --> external +``` + +1. The Actor developer declares which Connectors the Actor accepts in its input schema. +1. When you run the Actor, you select an eligible Connector in the input form. If you don't have one yet, you can create and authorize a new Connector in advance under **Settings > API & Integrations**. +1. When the Actor sends an MCP request to `APIFY_MCP_PROXY_URL/`, the Apify MCP Proxy validates the request, injects your credentials, and forwards it to the upstream MCP server the Connector is authorized against. + +The Actor code uses a standard MCP client - no Apify-specific SDK is required. + +## Security model + +MCP Connectors are designed so that the Actor never holds your credentials, and you stay in control of what the Actor can do with them. + +- _Your credentials stay private_. The Actor code never sees your tokens or API keys. The platform injects them on your behalf before forwarding each request. +- _You control which Connectors an Actor can access_. An Actor can only use Connectors you explicitly provide in the input. It cannot reach your other Connectors. +- _Actors are held to what they declare_. The proxy enforces that an Actor can only call tools it explicitly declared in its input schema. It cannot use your Connector to call anything beyond that, regardless of what the Connector supports. +- _Access ends when the run ends_. The proxy session expires as soon as the Actor run finishes. + +For the developer-side controls and tool-permission model, see [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors#tool-permissions). + +## Authentication methods + +When you create a Connector, the platform inspects the MCP server URL you provide and offers the authentication methods that server supports. + +| Method | When to use | +| --- | --- | +| _API key or bearer token_ | The MCP server uses a static API key or personal access token (PAT). | +| _OAuth_ | The server supports OAuth and either (a) supports Dynamic Client Registration (DCR), so Apify registers an OAuth client automatically, or (b) Apify provides a managed OAuth client for that service. | +| _Own OAuth client_ | The server uses OAuth but neither DCR nor an Apify-managed client is available. You register your own OAuth app with the provider and supply the credentials to Apify. | + +At launch, Notion and Supabase can be connected with no OAuth app setup on your side. Services such as GitHub, Slack, Google, and Microsoft require the Own OAuth Client flow - the same approach used by Claude Code, VS Code, and ChatGPT integrations. + +For step-by-step instructions on creating, authorizing, and managing Connectors, see [Account settings - MCP Connectors](/platform/console/settings#mcp-connectors). + +## Use cases + +Typical patterns that MCP Connectors enable: + +- _Push results to user tools_. An Actor that scrapes data on a schedule writes the output to a Notion database, a Supabase table, or a Slack channel the user owns - without the Actor ever holding a Notion API key or a Slack token. +- _Combine Apify scraping with the user's own integrations_. An Actor crawls a list of companies, then enriches the output by calling MCP tools the user has connected (CRM, project tracker, internal database). +- _Multi-service workflows_. An Actor that monitors something can post a message to Slack on one condition and write a row to a database on another, with both connections supplied by the user at runtime. +- _Reusable utility Actors_. A single Actor takes a generic input (a dataset ID, a URL, a search query) and one or more user-supplied Connectors as the destination, so the same Actor works across many services. + +## Current limitations + +- _Apify-managed OAuth clients are limited at launch_. Only Notion and Supabase work without OAuth app registration. For other OAuth-based services (GitHub, Slack, Google, Microsoft, and others), use the Own OAuth Client flow. +- _Per-tool restrictions on Connectors are not editable in the UI_. The platform discovers and displays the tools a Connector exposes, but the Connector itself does not yet support restricting individual tools. All discovered tools are allowed by default at the Connector level. Tool restrictions can still be enforced from the Actor side through the input schema - see [Tool permissions](/platform/integrations/mcp-connectors/use-in-actors#tool-permissions). +- _Tools are discovered once_. Tool discovery happens when you first authorize a Connector. There is no automatic re-discovery if the upstream server adds new tools. + +## Next steps + +- [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors) - declare Connectors in your input schema, connect from TypeScript or Python, and configure tool permissions. +- [Account settings - MCP Connectors](/platform/console/settings#mcp-connectors) - create, authorize, and manage Connectors in Apify Console. +- [Apify MCP server](/platform/integrations/mcp) - expose Apify Actors as MCP tools to outside AI clients. diff --git a/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md b/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md new file mode 100644 index 0000000000..1a3e910a8f --- /dev/null +++ b/sources/platform/integrations/ai/mcp-connectors/using-connectors-in-actors.md @@ -0,0 +1,455 @@ +--- +title: Build Actors with MCP Connectors +sidebar_label: Build with Connectors +description: Declare MCP Connectors in your Actor input schema, connect to them from TypeScript or Python, and apply tool-permission constraints at runtime. +sidebar_position: 1 +slug: /integrations/mcp-connectors/use-in-actors +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide explains how to build Actors that accept [MCP Connectors](/platform/integrations/mcp-connectors) as input, connect to them at runtime, and constrain which tools they can call. + +## Declare Connectors in the input schema + +To accept MCP Connectors as input, set `resourceType: "mcpConnector"` on the input field. This renders a Connector picker in Apify Console and enforces which Connectors are compatible with the Actor. + +### Single Connector + +For an Actor that uses one Connector, set `type` to `string`: + +```json +{ + "slackConnector": { + "title": "Slack Connector", + "description": "Connector to your Slack workspace", + "type": "string", + "resourceType": "mcpConnector", + "mcpServers": [ + { "url": "https://mcp.slack.com/mcp" } + ] + } +} +``` + +At runtime, the input value is a single Connector ID: + +```json +{ "slackConnector": "conn_abc123" } +``` + +### Multiple Connectors + +For an Actor that accepts several Connectors, set `type` to `array`: + +```json +{ + "mcpConnectors": { + "title": "MCP Connectors", + "description": "MCP server connections for this Actor to use", + "type": "array", + "resourceType": "mcpConnector", + "mcpServers": [ + { "url": "*" } + ] + } +} +``` + +At runtime, the input value is an array of Connector IDs: + +```json +{ "mcpConnectors": ["conn_abc123", "conn_def456"] } +``` + +## The `mcpServers` rule list + +Each entry in `mcpServers` is an independent rule that defines an eligible Connector by the upstream server URL it targets and the tools it must support. A Connector is eligible if it satisfies at least one entry: its server URL matches the entry's `url` pattern and it meets the entry's `tools` constraints. + +The rules serve two purposes at once: + +- _Eligibility filter_ - the Connector picker in the input form only offers Connectors that match at least one rule. +- _Runtime ceiling_ - the proxy holds the Actor to its declaration. The Actor can only see (through a filtered `tools/list`) and call (through a guarded `tools/call`) tools that fall within the rule it matched. + +### `url` + +URL pattern of the server an entry targets. The `*` wildcard matches zero or more characters. + +```json +"mcpServers": [ + { "url": "https://mcp.slack.com/mcp" }, + { "url": "https://*.slack.com/*" }, + { "url": "*" } +] +``` + +### `tools.required` + +An optional array of tool name patterns. For each pattern, the Connector must support at least one tool with a matching name. The `*` wildcard matches zero or more characters. Omit `required` (or use `["*"]`) to place no restriction on tool names. + +```json +"mcpServers": [ + { + "url": "https://mcp.slack.com/mcp", + "tools": { + "required": ["send_message", "list_channels", "post_*"] + } + } +] +``` + +### Behavioral hints + +Four hint fields constrain which tools are permitted based on their [MCP tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations). When a hint is omitted, it imposes no restriction. When set to an explicit `true` or `false`, a tool passes only if its effective hint value matches. If the upstream server does not annotate a tool, the MCP specification default applies. + +| Hint | Omitted | Explicitly `true` | Explicitly `false` | +| --- | --- | --- | --- | +| `readOnly` | No restriction | Read-only tools only | Mutating tools only (includes unannotated tools - MCP default is `false`) | +| `destructive` | No restriction | Destructive tools only (includes unannotated tools - MCP default is `true`) | Non-destructive tools only | +| `idempotent` | No restriction | Idempotent tools only | Non-idempotent tools only (includes unannotated tools - MCP default is `false`) | +| `openWorld` | No restriction | Open-world tools only (includes unannotated tools - MCP default is `true`) | Closed-world tools only | + +Example combining `required` patterns with hints: + +```json +"mcpServers": [ + { + "url": "https://mcp.example.com/*", + "tools": { + "required": ["read_*"], + "readOnly": true, + "destructive": false + } + } +] +``` + +## Input schema reference + +```typescript +// Single Connector (type: "string") +{ + title: string; // Required. + description: string; // Required. + type: "string"; + resourceType: "mcpConnector"; + mcpServers: McpServer[]; // Required. At least one entry. + + editor?: "resourcePicker" // Default. Shows a Connector picker in the UI. + | "textfield" // Accepts a Connector ID as free text. + | "hidden"; + + nullable?: boolean; + default?: string; + prefill?: string; + example?: string; + sectionCaption?: string; + sectionDescription?: string; +} + +// Multiple Connectors (type: "array") +{ + title: string; + description: string; + type: "array"; + resourceType: "mcpConnector"; + mcpServers: McpServer[]; + + editor?: "resourcePicker" // Default. Shows a Connector picker in the UI. + | "hidden"; + + minItems?: number; + maxItems?: number; + uniqueItems?: boolean; + + nullable?: boolean; + default?: string[]; + prefill?: string[]; + example?: string[]; + sectionCaption?: string; + sectionDescription?: string; +} + +// McpServer entry +{ + url: string; // URL or pattern. Use "*" to accept any server. + tools?: { + required?: string[]; // Tool name patterns. Omit or ["*"] for all tools. + readOnly?: boolean; + destructive?: boolean; + idempotent?: boolean; + openWorld?: boolean; + }; +} +``` + +## Examples + +### Read-only Slack monitor + +```json +{ + "properties": { + "slackConnector": { + "title": "Slack Connector", + "description": "Read-only access to your Slack workspace", + "type": "string", + "resourceType": "mcpConnector", + "mcpServers": [ + { + "url": "https://mcp.slack.com/mcp", + "tools": { + "required": ["list_*", "get_*", "read_*"], + "readOnly": true, + "destructive": false, + "idempotent": true + } + } + ] + } + } +} +``` + +### General-purpose agent + +Any server, any tools: + +```json +{ + "properties": { + "mcpConnectors": { + "title": "MCP Connectors", + "description": "Give this Actor access to any MCP servers you want it to use", + "type": "array", + "resourceType": "mcpConnector", + "mcpServers": [ + { "url": "*" } + ] + } + } +} +``` + +### Multi-service messaging + +Multiple allowed servers, send-only tools: + +```json +{ + "properties": { + "messagingConnectors": { + "title": "Messaging Connectors", + "description": "Connections to messaging services for sending notifications", + "type": "array", + "resourceType": "mcpConnector", + "mcpServers": [ + { + "url": "https://mcp.slack.com/mcp", + "tools": { "required": ["send_message", "post_*", "list_channels"] } + }, + { + "url": "https://mcp.discord.com/mcp", + "tools": { "required": ["send_message", "post_*", "list_channels"] } + } + ] + } + } +} +``` + +### Output-writing Actor + +Any server that supports at least one output-writing tool: + +```json +{ + "properties": { + "outputConnectors": { + "title": "Output Connectors", + "description": "Connectors to any MCP servers that support at least one output-writing tool", + "type": "array", + "resourceType": "mcpConnector", + "mcpServers": [ + { "url": "*", "tools": { "required": ["send_*"] } }, + { "url": "*", "tools": { "required": ["post_*"] } }, + { "url": "*", "tools": { "required": ["write_*"] } }, + { "url": "*", "tools": { "required": ["log_*"] } } + ] + } + } +} +``` + +## Connect from the Actor + +Every Actor run receives two environment variables for MCP Connector access. + +| Variable | Description | +| --- | --- | +| `APIFY_MCP_PROXY_URL` | Base URL of the Apify MCP Proxy. Connect to a Connector at `${APIFY_MCP_PROXY_URL}/`. | +| `APIFY_TOKEN` | API token of the user who started the Actor. Use it as the bearer token for proxy requests. | + +The Actor uses a standard MCP client to connect to the proxy URL with the token as a bearer credential. No Apify-specific MCP SDK is required. + + + + +Install the [official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk): + +```bash +npm install @modelcontextprotocol/sdk +``` + +```typescript +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; +import { Actor } from 'apify'; + +await Actor.init(); + +const input = await Actor.getInputOrThrow<{ slackConnector: string }>(); +const connectorId = input.slackConnector; + +const transport = new StreamableHTTPClientTransport( + new URL(`${process.env.APIFY_MCP_PROXY_URL}/${connectorId}`), + { + requestInit: { + headers: { + Authorization: `Bearer ${process.env.APIFY_TOKEN}`, + }, + }, + }, +); + +const client = new Client({ name: 'my-actor', version: '1.0.0' }); +await client.connect(transport); + +const { tools } = await client.listTools(); +console.log(tools.map((t) => t.name)); + +const result = await client.callTool({ + name: 'send_message', + arguments: { channel: '#general', text: 'Hello from Apify!' }, +}); + +await client.close(); +await Actor.exit(); +``` + + + + +Install the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk): + +```bash +pip install mcp httpx apify +``` + +```python +import asyncio +import os + +import httpx +from apify import Actor +from mcp import ClientSession +from mcp.client.streamable_http import streamable_http_client + +async def main(): + async with Actor: + input_data = await Actor.get_input() + connector_id = input_data['slack_connector'] + + proxy_url = os.environ['APIFY_MCP_PROXY_URL'] + token = os.environ['APIFY_TOKEN'] + + async with httpx.AsyncClient( + headers={"Authorization": f"Bearer {token}"}, + ) as http_client: + async with streamable_http_client( + f"{proxy_url}/{connector_id}", + http_client=http_client, + ) as (read, write, _): + async with ClientSession(read, write) as session: + await session.initialize() + tools = (await session.list_tools()).tools + result = await session.call_tool( + "send_message", + arguments={ + "channel": "#general", + "text": "Hello from Apify!", + }, + ) + +asyncio.run(main()) +``` + + + + +## Connect multiple Connectors + +When the input field uses `type: "array"`, create one MCP client per Connector ID. Each Connector gets its own session through the proxy. + +```typescript +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; + +const connectorIds: string[] = input.mcpConnectors; + +const clients = await Promise.all( + connectorIds.map(async (connectorId) => { + const transport = new StreamableHTTPClientTransport( + new URL(`${process.env.APIFY_MCP_PROXY_URL}/${connectorId}`), + { + requestInit: { + headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` }, + }, + }, + ); + const client = new Client({ name: 'my-actor', version: '1.0.0' }); + await client.connect(transport); + return client; + }), +); +``` + +## Tool permissions + +Three independent layers control which tools are accessible when an Actor uses a Connector. A tool is available only if it passes every configured layer. An unconfigured layer imposes no restriction. + +```mermaid +flowchart TD + A([Tool call]) + B["Layer 0 — Auth-level permissions
OAuth scopes or API key / PAT permissions
granted when the Connector was authorized"] + C["Layer 1 — Connector tool allowlist
All tools discovered on the upstream server
are allowed by default"] + D["Layer 2 — Actor input schema
Tool constraints in mcpServers
act as eligibility filter and runtime ceiling"] + E([Tool available]) + + A --> B + B -->|passes| C + C -->|passes| D + D -->|passes| E +``` + +### Layer 0 - authentication scope + +When you authorize a Connector, the permissions granted at the auth step (OAuth scopes, or the permissions configured on an API key or PAT) bound everything that follows. A tool that requires write access to a resource the token cannot reach will fail at the upstream MCP server, regardless of what the other layers allow. + +### Layer 1 - Connector tool allowlist + +At the Connector level, all tools the upstream MCP server discovers are allowed by default. The set of discovered tools is fixed at the time the Connector is authorized. + +### Layer 2 - input schema constraints + +The Actor's `mcpServers[].tools` declaration in the input schema is the strongest enforcement point because it ties tool access to a specific Actor. The proxy filters `tools/list` responses to only show the declared tools and rejects `tools/call` requests for any tool outside the declared set. + +For the full schema, see [The `mcpServers` rule list](#the-mcpservers-rule-list). + +## Related pages + +- [MCP Connectors overview](/platform/integrations/mcp-connectors) +- [Input schema specification - resource type](/platform/actors/development/actor-definition/input-schema/specification/v1#resource-type) +- [Account settings - MCP Connectors](/platform/console/settings#mcp-connectors) +- [Apify environment variables](/platform/actors/development/programming-interface/environment-variables#system-environment-variables) diff --git a/sources/platform/integrations/ai/mcp/index.md b/sources/platform/integrations/ai/mcp/index.md index bf248a37e5..b62f7d7d68 100644 --- a/sources/platform/integrations/ai/mcp/index.md +++ b/sources/platform/integrations/ai/mcp/index.md @@ -22,6 +22,12 @@ and enables AI coding assistants to access Apify documentation and tutorials. +:::info Apify MCP server vs MCP Connectors + +This page covers the Apify MCP server, which exposes Apify Actors as tools to outside AI clients. If you are building an Actor that needs to call third-party MCP servers (such as Notion or Slack) on a user's behalf, see [MCP Connectors](/platform/integrations/mcp-connectors) instead. + +::: + ## Prerequisites Before connecting your AI to Apify, you'll need three things: diff --git a/sources/platform/integrations/index.mdx b/sources/platform/integrations/index.mdx index 6a37a54800..7b0eca0fc1 100644 --- a/sources/platform/integrations/index.mdx +++ b/sources/platform/integrations/index.mdx @@ -259,6 +259,13 @@ These integrations allow you to use Apify Actors as tools and data sources. If y imageUrlDarkTheme="/img/platform/integrations/mcp-logo-white.png" smallImage /> + Date: Mon, 25 May 2026 18:13:06 +0200 Subject: [PATCH 2/3] docs: tighten MCP Connectors landing voice Trim the opening sentence, convert italic-led bullet lists to flat declarative form, and inline the inbound/outbound disambiguation callout. --- .../integrations/ai/mcp-connectors/index.md | 36 +++++++++---------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/sources/platform/integrations/ai/mcp-connectors/index.md b/sources/platform/integrations/ai/mcp-connectors/index.md index 819b89b628..3411d0ad50 100644 --- a/sources/platform/integrations/ai/mcp-connectors/index.md +++ b/sources/platform/integrations/ai/mcp-connectors/index.md @@ -6,15 +6,11 @@ sidebar_position: 0.5 slug: /integrations/mcp-connectors --- -MCP Connectors let Actors call third-party services - Notion, Slack, GitHub, Sentry, Supabase, and others - through [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) on your behalf, using your credentials, without ever exposing those credentials to the Actor code. +MCP Connectors let Actors call third-party services through [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) on your behalf, using your credentials. Supported services include Notion, Slack, GitHub, Sentry, and Supabase. You authorize a Connector once in your account settings. When you run an Actor that accepts Connectors, the input form shows a picker filtered to those compatible with the Actor's requirements. At runtime, the Apify platform injects your credentials server-side. The Actor never sees a token. -:::info Apify MCP server vs MCP Connectors - -The [Apify MCP server](/platform/integrations/mcp) exposes Apify Actors as tools to outside AI clients (Claude, ChatGPT, Cursor, and others). MCP Connectors do the opposite: they let Apify Actors call external MCP servers as tools. The two features are independent and can be used together or separately. - -::: +MCP Connectors are distinct from the [Apify MCP server](/platform/integrations/mcp). The MCP server exposes Apify Actors as tools to outside AI clients (Claude, ChatGPT, Cursor, and others); MCP Connectors do the opposite, letting Apify Actors call external MCP servers as tools. The two features are independent and can be used together or separately. ## How it works @@ -44,10 +40,10 @@ The Actor code uses a standard MCP client - no Apify-specific SDK is required. MCP Connectors are designed so that the Actor never holds your credentials, and you stay in control of what the Actor can do with them. -- _Your credentials stay private_. The Actor code never sees your tokens or API keys. The platform injects them on your behalf before forwarding each request. -- _You control which Connectors an Actor can access_. An Actor can only use Connectors you explicitly provide in the input. It cannot reach your other Connectors. -- _Actors are held to what they declare_. The proxy enforces that an Actor can only call tools it explicitly declared in its input schema. It cannot use your Connector to call anything beyond that, regardless of what the Connector supports. -- _Access ends when the run ends_. The proxy session expires as soon as the Actor run finishes. +- Your credentials stay private. The Actor code never sees your tokens or API keys. The platform injects them on your behalf before forwarding each request. +- You control which Connectors an Actor can access. An Actor can only use Connectors you explicitly provide in the input. It cannot reach your other Connectors. +- Actors are held to what they declare. The proxy enforces that an Actor can only call tools it explicitly declared in its input schema. It cannot use your Connector to call anything beyond that, regardless of what the Connector supports. +- Access ends when the run ends. The proxy session expires as soon as the Actor run finishes. For the developer-side controls and tool-permission model, see [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors#tool-permissions). @@ -57,9 +53,9 @@ When you create a Connector, the platform inspects the MCP server URL you provid | Method | When to use | | --- | --- | -| _API key or bearer token_ | The MCP server uses a static API key or personal access token (PAT). | -| _OAuth_ | The server supports OAuth and either (a) supports Dynamic Client Registration (DCR), so Apify registers an OAuth client automatically, or (b) Apify provides a managed OAuth client for that service. | -| _Own OAuth client_ | The server uses OAuth but neither DCR nor an Apify-managed client is available. You register your own OAuth app with the provider and supply the credentials to Apify. | +| API key or bearer token | The MCP server uses a static API key or personal access token (PAT). | +| OAuth | The server supports OAuth and either (a) supports Dynamic Client Registration (DCR), so Apify registers an OAuth client automatically, or (b) Apify provides a managed OAuth client for that service. | +| Own OAuth client | The server uses OAuth but neither DCR nor an Apify-managed client is available. You register your own OAuth app with the provider and supply the credentials to Apify. | At launch, Notion and Supabase can be connected with no OAuth app setup on your side. Services such as GitHub, Slack, Google, and Microsoft require the Own OAuth Client flow - the same approach used by Claude Code, VS Code, and ChatGPT integrations. @@ -69,16 +65,16 @@ For step-by-step instructions on creating, authorizing, and managing Connectors, Typical patterns that MCP Connectors enable: -- _Push results to user tools_. An Actor that scrapes data on a schedule writes the output to a Notion database, a Supabase table, or a Slack channel the user owns - without the Actor ever holding a Notion API key or a Slack token. -- _Combine Apify scraping with the user's own integrations_. An Actor crawls a list of companies, then enriches the output by calling MCP tools the user has connected (CRM, project tracker, internal database). -- _Multi-service workflows_. An Actor that monitors something can post a message to Slack on one condition and write a row to a database on another, with both connections supplied by the user at runtime. -- _Reusable utility Actors_. A single Actor takes a generic input (a dataset ID, a URL, a search query) and one or more user-supplied Connectors as the destination, so the same Actor works across many services. +- Push results to user tools. An Actor that scrapes data on a schedule writes the output to a Notion database, a Supabase table, or a Slack channel the user owns - without the Actor ever holding a Notion API key or a Slack token. +- Combine Apify scraping with the user's own integrations. An Actor crawls a list of companies, then enriches the output by calling MCP tools the user has connected (CRM, project tracker, internal database). +- Multi-service workflows. An Actor that monitors something can post a message to Slack on one condition and write a row to a database on another, with both connections supplied by the user at runtime. +- Reusable utility Actors. A single Actor takes a generic input (a dataset ID, a URL, a search query) and one or more user-supplied Connectors as the destination, so the same Actor works across many services. ## Current limitations -- _Apify-managed OAuth clients are limited at launch_. Only Notion and Supabase work without OAuth app registration. For other OAuth-based services (GitHub, Slack, Google, Microsoft, and others), use the Own OAuth Client flow. -- _Per-tool restrictions on Connectors are not editable in the UI_. The platform discovers and displays the tools a Connector exposes, but the Connector itself does not yet support restricting individual tools. All discovered tools are allowed by default at the Connector level. Tool restrictions can still be enforced from the Actor side through the input schema - see [Tool permissions](/platform/integrations/mcp-connectors/use-in-actors#tool-permissions). -- _Tools are discovered once_. Tool discovery happens when you first authorize a Connector. There is no automatic re-discovery if the upstream server adds new tools. +- Apify-managed OAuth clients are limited at launch. Only Notion and Supabase work without OAuth app registration. For other OAuth-based services (GitHub, Slack, Google, Microsoft, and others), use the Own OAuth Client flow. +- Per-tool restrictions on Connectors are not editable in the UI. The platform discovers and displays the tools a Connector exposes, but the Connector itself does not yet support restricting individual tools. All discovered tools are allowed by default at the Connector level. Tool restrictions can still be enforced from the Actor side through the input schema - see [Tool permissions](/platform/integrations/mcp-connectors/use-in-actors#tool-permissions). +- Tools are discovered once. Tool discovery happens when you first authorize a Connector. There is no automatic re-discovery if the upstream server adds new tools. ## Next steps From 08d37e68ef5c05f513ed789bed81c058efdbd4b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Olender?= <92638966+TC-MO@users.noreply.github.com> Date: Mon, 25 May 2026 22:10:12 +0200 Subject: [PATCH 3/3] docs: clarify MCP Connectors credential boundary and entry points Distinguish APIFY_TOKEN (which the Actor uses to call the proxy) from the third-party credential (which never enters the Actor) across the landing, develop_ai_agents, and secret_input pages. Add descriptions and renamed labels to the MCP server and MCP Connectors cards on the Integrations index. Add a short "Run an Actor with a Connector" section to the landing for end-user discovery, and reframe the Authentication methods cross-link from instructional to action-oriented. --- .../actor_definition/input_schema/secret_input.md | 2 +- .../development/quick-start/develop_ai_agents.md | 2 +- .../platform/integrations/ai/mcp-connectors/index.md | 10 +++++++--- sources/platform/integrations/index.mdx | 4 +++- 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/sources/platform/actors/development/actor_definition/input_schema/secret_input.md b/sources/platform/actors/development/actor_definition/input_schema/secret_input.md index 61cdb40709..7932419fdd 100644 --- a/sources/platform/actors/development/actor_definition/input_schema/secret_input.md +++ b/sources/platform/actors/development/actor_definition/input_schema/secret_input.md @@ -9,7 +9,7 @@ The secret input feature lets you mark specific input fields of an Actor as sens :::tip MCP Connectors for third-party credentials -If the third-party service you need exposes a [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server, consider using [MCP Connectors](/platform/integrations/mcp-connectors) instead. The user authorizes the service once in their account settings, and the Actor receives a Connector ID rather than a credential - the token itself never enters the Actor. For credentials without an MCP server (database passwords, generic API keys), continue to use `isSecret: true`. +If the third-party service you need exposes a [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server, consider using [MCP Connectors](/platform/integrations/mcp-connectors) instead. The user authorizes the service once in their account settings, and the Actor receives a Connector ID rather than a credential. The service token, API key, or PAT stays server-side and is injected by the MCP Proxy at runtime. For credentials without an MCP server (database passwords, generic API keys), continue to use `isSecret: true`. ::: diff --git a/sources/platform/actors/development/quick-start/develop_ai_agents.md b/sources/platform/actors/development/quick-start/develop_ai_agents.md index 656a6546a9..4da5917f59 100644 --- a/sources/platform/actors/development/quick-start/develop_ai_agents.md +++ b/sources/platform/actors/development/quick-start/develop_ai_agents.md @@ -80,7 +80,7 @@ AI Sandbox runs on a Debian image with Node.js version 24 and Python 3.11 pre-in ## Connect to user services with MCP Connectors -If your agent needs to act on a user's third-party accounts - posting to Slack, writing to Notion, querying GitHub - use [MCP Connectors](/platform/integrations/mcp-connectors). The user authorizes each service once in their account settings, and your Actor receives a Connector ID as input. The token itself never enters the Actor: the Apify MCP Proxy injects credentials server-side at runtime. Declare which services your Actor accepts in the input schema with `resourceType: "mcpConnector"`. See [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors) for the full schema and code samples. +If your agent needs to act on a user's third-party accounts - posting to Slack, writing to Notion, querying GitHub - use [MCP Connectors](/platform/integrations/mcp-connectors). The user authorizes each service once in their account settings, and your Actor receives a Connector ID as input. Your Actor uses its Apify run token to reach the MCP Proxy; the third-party service credential stored in the Connector stays server-side and never enters the Actor. Declare which services your Actor accepts in the input schema with `resourceType: "mcpConnector"`. See [Build Actors with MCP Connectors](/platform/integrations/mcp-connectors/use-in-actors) for the full schema and code samples. ## Access LLMs with OpenRouter diff --git a/sources/platform/integrations/ai/mcp-connectors/index.md b/sources/platform/integrations/ai/mcp-connectors/index.md index 3411d0ad50..49c6f67760 100644 --- a/sources/platform/integrations/ai/mcp-connectors/index.md +++ b/sources/platform/integrations/ai/mcp-connectors/index.md @@ -8,7 +8,7 @@ slug: /integrations/mcp-connectors MCP Connectors let Actors call third-party services through [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) on your behalf, using your credentials. Supported services include Notion, Slack, GitHub, Sentry, and Supabase. -You authorize a Connector once in your account settings. When you run an Actor that accepts Connectors, the input form shows a picker filtered to those compatible with the Actor's requirements. At runtime, the Apify platform injects your credentials server-side. The Actor never sees a token. +You authorize a Connector once in your account settings. When you run an Actor that accepts Connectors, the input form shows a picker filtered to those compatible with the Actor's requirements. At runtime, the Apify platform injects your service credentials server-side. The Actor authenticates to the proxy with its Apify run token, never with your third-party credentials. MCP Connectors are distinct from the [Apify MCP server](/platform/integrations/mcp). The MCP server exposes Apify Actors as tools to outside AI clients (Claude, ChatGPT, Cursor, and others); MCP Connectors do the opposite, letting Apify Actors call external MCP servers as tools. The two features are independent and can be used together or separately. @@ -40,7 +40,7 @@ The Actor code uses a standard MCP client - no Apify-specific SDK is required. MCP Connectors are designed so that the Actor never holds your credentials, and you stay in control of what the Actor can do with them. -- Your credentials stay private. The Actor code never sees your tokens or API keys. The platform injects them on your behalf before forwarding each request. +- Your third-party credentials stay private. The Actor uses its Apify run token to reach the proxy; the OAuth token, API key, or PAT stored in the Connector never enters the Actor. The platform injects it server-side before forwarding each request. - You control which Connectors an Actor can access. An Actor can only use Connectors you explicitly provide in the input. It cannot reach your other Connectors. - Actors are held to what they declare. The proxy enforces that an Actor can only call tools it explicitly declared in its input schema. It cannot use your Connector to call anything beyond that, regardless of what the Connector supports. - Access ends when the run ends. The proxy session expires as soon as the Actor run finishes. @@ -59,7 +59,11 @@ When you create a Connector, the platform inspects the MCP server URL you provid At launch, Notion and Supabase can be connected with no OAuth app setup on your side. Services such as GitHub, Slack, Google, and Microsoft require the Own OAuth Client flow - the same approach used by Claude Code, VS Code, and ChatGPT integrations. -For step-by-step instructions on creating, authorizing, and managing Connectors, see [Account settings - MCP Connectors](/platform/console/settings#mcp-connectors). +Create and manage your Connectors in [Settings > API & Integrations > MCP Connectors](/platform/console/settings#mcp-connectors). + +## Run an Actor with a Connector + +When you run an Actor that accepts MCP Connectors, the input form shows a Connector picker filtered to those compatible with the Actor's requirements. Pick one of your authorized Connectors, or create a new one inline. To set Connectors up in advance, see [Account settings - MCP Connectors](/platform/console/settings#mcp-connectors). ## Use cases diff --git a/sources/platform/integrations/index.mdx b/sources/platform/integrations/index.mdx index 7b0eca0fc1..4f50c1d4c7 100644 --- a/sources/platform/integrations/index.mdx +++ b/sources/platform/integrations/index.mdx @@ -253,7 +253,8 @@ These integrations allow you to use Apify Actors as tools and data sources. If y smallImage />