Skip to content

Commit a7f8efd

Browse files
TC-MOTC-MO
authored
docs: add MCP Connectors documentation (#2568)
Introduces sources/platform/integrations/ai/mcp-connectors/. Extends the input schema spec with the mcpConnector resourceType adds APIFY_MCP_PROXY_URL to environment variables documents Connector management under console settings Cross-links related AI pages and adds Connector capitalization to the terminology standards.
1 parent 5329697 commit a7f8efd

11 files changed

Lines changed: 676 additions & 19 deletions

File tree

‎sources/platform/actors/development/actor_definition/input_schema/secret_input.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ slug: /actors/development/actor-definition/input-schema/secret-input
77

88
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.
99

10+
:::tip MCP connectors for third-party credentials
11+
12+
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`.
13+
14+
:::
15+
1016
## How to set a secret input field
1117

1218
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:

‎sources/platform/actors/development/actor_definition/input_schema/specification.md‎

Lines changed: 47 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -889,7 +889,8 @@ As with objects, the sub-schema feature for arrays only works for level 1 sub-pr
889889
### Resource type
890890

891891
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.
892-
Currently, it supports storage resources only, allowing the reference of a Dataset, Key-Value Store or Request Queue.
892+
893+
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.
893894

894895
For Actor developers, the resource input value is a string representing either the resource ID or (unique) name.
895896
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:
932933

933934
#### Single value properties
934935

935-
| Property | Value | Required | Description |
936-
|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
937-
| `type` | `string` | Yes | Specifies the type of input - `string` for single value. |
938-
| `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`. |
939-
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li></ul> | Yes | Type of Apify Platform resource |
940-
| `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. |
941-
| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
942-
| `minLength` | Integer | No | Minimum length of the string. |
943-
| `maxLength` | Integer | No | Maximum length of the string. |
936+
| Property | Value | Required | Description |
937+
| --- | --- | --- | --- |
938+
| `type` | `string` | Yes | Specifies the type of input - `string` for single value. |
939+
| `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`. |
940+
| `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. |
941+
| `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. |
942+
| `pattern` | String | No | Regular expression that will be used to validate the input. If validation fails, the Actor will not run. |
943+
| `minLength` | Integer | No | Minimum length of the string. |
944+
| `maxLength` | Integer | No | Maximum length of the string. |
944945

945946
#### Multiple values properties
946947

947-
| Property | Value | Required | Description |
948-
|-----------------------|-----------------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
949-
| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. |
950-
| `editor` | One of <ul><li>`resourcePicker`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
951-
| `resourceType` | One of <ul><li>`dataset`</li><li>`keyValueStore`</li><li>`requestQueue`</li></ul> | Yes | Type of Apify Platform resource |
952-
| `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. |
953-
| `minItems` | Integer | No | Minimum number of items the array can contain. |
954-
| `maxItems` | Integer | No | Maximum number of items the array can contain. |
948+
| Property | Value | Required | Description |
949+
| --- | --- | --- | --- |
950+
| `type` | `array` | Yes | Specifies the type of input - `array` for multiple values. |
951+
| `editor` | One of <ul><li>`resourcePicker`</li><li>`hidden`</li></ul> | No | Visual editor used for <br/>the input field. Defaults to `resourcePicker`. |
952+
| `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. |
953+
| `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. |
954+
| `minItems` | Integer | No | Minimum number of items the array can contain. |
955+
| `maxItems` | Integer | No | Maximum number of items the array can contain. |
955956

956957
#### Resource permissions
957958

@@ -966,6 +967,34 @@ This setting defines runtime access only and doesn't change field visibility or
966967

967968
:::
968969

970+
#### MCP connector resource type
971+
972+
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.
973+
974+
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:
975+
976+
```json
977+
{
978+
"slackConnector": {
979+
"title": "Slack connector",
980+
"description": "Read-only access to your Slack workspace",
981+
"type": "string",
982+
"resourceType": "mcpConnector",
983+
"mcpServers": [
984+
{
985+
"url": "https://mcp.slack.com/mcp",
986+
"tools": {
987+
"required": ["list_*", "get_*", "read_*"],
988+
"readOnly": true
989+
}
990+
}
991+
]
992+
}
993+
}
994+
```
995+
996+
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).
997+
969998
### Deprecation of `patternKey` and `patternValue`
970999

9711000
::::warning Deprecation notice

‎sources/platform/actors/development/programming_interface/environment_variables.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ System variables apply only to Actor runs and are never passed to builds - not e
6666
| `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. |
6767
| `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). |
6868
| `APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE` | Passphrase for the input secret key specified in `APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE`. |
69+
| `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. |
6970

7071

7172
<!-- vale Microsoft.RangeFormat = NO -->

‎sources/platform/actors/development/quick-start/develop_ai_agents.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,10 @@ AI Sandbox runs on a Debian image with Node.js version 24 and Python 3.11 pre-in
7878

7979
:::
8080

81+
## Connect to user services with MCP connectors
82+
83+
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.
84+
8185
## Access LLMs with OpenRouter
8286

8387
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.

‎sources/platform/console/settings.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,60 @@ In the **Session information** section, you can adjust the session configuration
3838

3939
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).
4040

41+
### MCP connectors
42+
43+
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).
44+
45+
#### Create a connector
46+
47+
1. Open **Settings > API & Integrations > MCP connectors** and click **Create new connector**.
48+
1. Enter the MCP server URL, for example:
49+
50+
```text
51+
https://mcp.slack.com/mcp
52+
https://api.notion.com/mcp
53+
https://mcp.sentry.io/mcp
54+
```
55+
56+
The platform inspects the URL and offers the authentication methods the server supports.
57+
58+
1. Choose an authentication method:
59+
60+
* _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.
61+
* _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.
62+
* _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.
63+
64+
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 and restrict which ones the connector permits.
65+
66+
#### Set up your own OAuth client
67+
68+
For providers without Apify-managed OAuth client setup (GitHub, Slack, Google, Microsoft Entra, and others), register an OAuth app yourself:
69+
70+
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)).
71+
1. Create a new OAuth app.
72+
1. Add the following Apify URL as an authorized redirect or callback URI:
73+
74+
```text
75+
https://console.apify.com/oauth/mcp-proxy
76+
```
77+
78+
1. Copy the client ID and client secret.
79+
1. In the connector creation modal, select **Own OAuth client** and provide:
80+
* Client ID
81+
* Client secret
82+
* Authorization URL (for example, `https://github.com/login/oauth/authorize`)
83+
* Token URL (for example, `https://github.com/login/oauth/access_token`)
84+
85+
This is the same approach used by Claude Code, VS Code, and ChatGPT integrations.
86+
87+
#### Reauthorize a connector
88+
89+
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.
90+
91+
#### Delete a connector
92+
93+
Click **Delete** on the connector card. The connector is removed immediately and can no longer be used by any Actor.
94+
4195
## Organizations
4296
4397
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).

‎sources/platform/integrations/ai/agent-onboarding.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Connect your AI agent or application to Apify - the platform for web scraping, d
1818
- _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).
1919
- _Datasets_ - Append-only storage for structured results. Every Actor run creates a default dataset. Export as JSON, CSV, Excel, XML, or RSS.
2020
- _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.
21+
- _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.
2122

2223
## Prerequisites
2324

0 commit comments

Comments
 (0)