# Universal MCP Connector (`lukaskrivka/universal-connector`) Actor Universal MCP Connector allows you to run arbitrary workflows on the Apify platform and then publish the results on other platforms that support MCP protocol (most popular platforms do) - **URL**: https://apify.com/lukaskrivka/universal-connector.md - **Developed by:** [Lukรกลก Kล™ivka](https://apify.com/lukaskrivka) (community) - **Categories:** Agents, AI, Automation - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README Universal MCP Connector allows you to run arbitrary workflows on the Apify platform and then publish the results onother platform that supports MCP protocol (most popular platforms do). > [!WARNING] > Don't choose state of the art LLMs to process large datasets as it can burn through your Apify credits. Experiment first with smaller workflows or cheaper (default) models. ### Features - Secure authentication by setting your API key or OAuth for the target MCP server directly in Apify Console. This Actor doesn't need to handle any credentials. - Connect one or multiple MCP servers at the same time, including Apify's MCP server. - Steer the agent with a custom query to choose appropriate actions across connected MCP servers (e.g. "on failing Actor run, create an issue on GitHub and send me message to Slack"). - LLM tokens are charged directly to your Apify account credits via [OpenRouter Actor](https://apify.com/apify/openrouter), no need to have account on OpenAI or Anthropic. - Automatic model selection via OpenRouter, which chooses the best model for your use case based on performance and cost. ### Authorization MCP connector credentials are stored securely inside Apify Console and are never exposed to the Actor code. You only need to set up the connection to your MCP server once in Apify Console and then you can use it in any Actor that supports MCP connectors. Once on the Actor Input page: 1. Choose an existing MCP connector or click on "Create new connector". 2. Fill in the MCP server URL, the input will automatically highlight if you can use OAuth directly (via dynamic client registration). 3. If OAuth is not available, you can provide an API key or create your own OAuth client on the target platform. 4. Once you create the connector, it will be available for all Actors that support MCP connectors. ### How to run You can use this connector either as primary workflow driver or as a post-processing step after running your main Actor. #### Directly Use prompt that suggests what data you need or what Actor to call. You can also process your stored data directly. Example prompt: ```Tell me what are the top 5 sushi restaurants in New York City but find me some critical reviews for each. Prefer using Google Maps Scraper by Compass. Send me the summary to Slack channel #sushi-recommendations.``` #### As an integration Attach this Actor as integration that runs after your main Actor finishes. You can use the payload template variables to pass any metadata from your main Actor run to the prompt of the MCP Connector. Example prompt: ```You are triggered after Apify's Google Maps Scraper finishes. Fetch dataset with ID {{resource.defaultDatasetId}} and summarize the results with focus of critical reviews. Send me the summary to Slack channel #sushi-recommendations.``` ### Current limitations These limitations are expected to be resolved in the future - Agents sometimes asks for permission but there is no way to answer it back. - Low reliability of operations. We need to improve the tool narrowing, system prompt and retry mechanism as well as the Apify MCP server itself. - Processing large datasets is not optimal as growing context can lead to inaccuracy or it might be too expensive. We expect this to improve with better pre-processing tools. - Requires to run the OpenRouter Actor on your account that requires small amount of memory ### Debugging Tool calls results and agent messages are stored in the key-value store of each run. # Actor input Schema ## `query` (type: `string`): The question or task for the agent. The agent will use the MCP tools to answer this question or complete the task. When used from Apify Integration, you can embed any ID from payload ## `llm` (type: `string`): The language model to use for the agent's reasoning and decision-making. openrouter/auto tends to choose small cheap models. ## `mcpConnectorIds` (type: `array`): Connector to the Apify MCP Server (for running Actors and fetching datasets) ## `useApifyDirectMcp` (type: `boolean`): Whether to use the direct connection to the Apify MCP Server (without going through the MCP Proxy). This is useful for testing and debugging, but not recommended for production use. ## Actor input object example ```json { "query": "Tell me what are the latest posts by humansofny on Instagram, check last 10 of them and give me a summary of repeating topics. Use the apify/instagram-post-scraper. Then create a new Notion page and write the summary there and give me back the link to that page.", "llm": "deepseek/deepseek-v4-flash", "useApifyDirectMcp": false } ```` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "query": "Tell me what are the latest posts by humansofny on Instagram, check last 10 of them and give me a summary of repeating topics. Use the apify/instagram-post-scraper. Then create a new Notion page and write the summary there and give me back the link to that page." }; // Run the Actor and wait for it to finish const run = await client.actor("lukaskrivka/universal-connector").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "Tell me what are the latest posts by humansofny on Instagram, check last 10 of them and give me a summary of repeating topics. Use the apify/instagram-post-scraper. Then create a new Notion page and write the summary there and give me back the link to that page." } # Run the Actor and wait for it to finish run = client.actor("lukaskrivka/universal-connector").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "query": "Tell me what are the latest posts by humansofny on Instagram, check last 10 of them and give me a summary of repeating topics. Use the apify/instagram-post-scraper. Then create a new Notion page and write the summary there and give me back the link to that page." }' | apify call lukaskrivka/universal-connector --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lukaskrivka/universal-connector", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Universal MCP Connector", "description": "Universal MCP Connector allows you to run arbitrary workflows on the Apify platform and then publish the results on other platforms that support MCP protocol (most popular platforms do)", "version": "0.0", "x-build-id": "lUafb6ReAz3u8AWdc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lukaskrivka~universal-connector/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lukaskrivka-universal-connector", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lukaskrivka~universal-connector/runs": { "post": { "operationId": "runs-sync-lukaskrivka-universal-connector", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lukaskrivka~universal-connector/run-sync": { "post": { "operationId": "run-sync-lukaskrivka-universal-connector", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "query": { "title": "User query", "type": "string", "description": "The question or task for the agent. The agent will use the MCP tools to answer this question or complete the task. When used from Apify Integration, you can embed any ID from payload" }, "llm": { "title": "Language model (big models can be expensive!)", "type": "string", "description": "The language model to use for the agent's reasoning and decision-making. openrouter/auto tends to choose small cheap models.", "default": "deepseek/deepseek-v4-flash" }, "mcpConnectorIds": { "title": "MCP Connectors (Don't forget to fill these)", "type": "array", "description": "Connector to the Apify MCP Server (for running Actors and fetching datasets)" }, "useApifyDirectMcp": { "title": "Use Apify Direct MCP (for testing locally)", "type": "boolean", "description": "Whether to use the direct connection to the Apify MCP Server (without going through the MCP Proxy). This is useful for testing and debugging, but not recommended for production use.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```