Skip to content

docs: add MCP Connectors documentation #2568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
TC-MO wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

docs: add MCP Connectors documentation #2568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ad965ce
docs: add MCP Connectors documentation
TC-MO May 25, 2026
5861ce9
docs: tighten MCP Connectors landing voice
TC-MO May 25, 2026
08d37e6
docs: clarify MCP Connectors credential boundary and entry points
TC-MO May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions sources/platform/actors/development/actor_definition/input_schema/secret_input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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`.

:::

## 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:
Expand Down
65 changes: 47 additions & 18 deletions sources/platform/actors/development/actor_definition/input_schema/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 <ul><li>`resourcePicker`</li><li>`textfield`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li></ul> | Yes | Type of Apify Platform resource |
| `resourcePermissions` | Array of strings; allowed values: <ul><li>`READ`</li><li>`WRITE`</li></ul> | 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 <ul><li>`resourcePicker`</li><li>`textfield`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li><li>`mcpConnector`</li></ul> | 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: <ul><li>`READ`</li><li>`WRITE`</li></ul> | 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 <ul><li>`resourcePicker`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li></ul> | Yes | Type of Apify Platform resource |
| `resourcePermissions` | Array of strings; allowed values: <ul><li>`READ`</li><li>`WRITE`</li></ul> | 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 <ul><li>`resourcePicker`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li><li>`mcpConnector`</li></ul> | Yes | Type of Apify Platform resource. Use `mcpConnector` to accept [MCP Connectors](/platform/integrations/mcp-connectors) as input. |
| `resourcePermissions` | Array of strings; allowed values: <ul><li>`READ`</li><li>`WRITE`</li></ul> | 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

Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions sources/platform/actors/development/programming_interface/environment_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}/<connectorId>` using `APIFY_TOKEN` as the bearer token. |


<!-- vale Microsoft.RangeFormat = NO -->
Expand Down
4 changes: 4 additions & 0 deletions sources/platform/actors/development/quick-start/develop_ai_agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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

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.
Expand Down
54 changes: 54 additions & 0 deletions sources/platform/console/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
1 change: 1 addition & 0 deletions sources/platform/integrations/ai/agent-onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading