apify-mcp-server

Exposes thousands of Apify Actors as standardized MCP tools through the ActorsMcpServer class, which registers tools with structured JSON schemas and handles MCP protocol operations (tool discovery, invocation, result streaming). The server implements the Model Context Protocol specification, enabling AI clients (Claude Desktop, VS Code, ChatGPT) to discover and invoke Actors as first-class tools with type-safe input/output contracts.

Supports three transport protocols for MCP communication: STDIO for local CLI usage (Claude Desktop integration), SSE for legacy streaming, and HTTP for hosted services. The transport layer abstracts protocol differences, allowing the same ActorsMcpServer core to operate across deployment contexts (local, Apify Actor standby mode, or hosted service at mcp.apify.com) without code changes.

Provides built-in internal helper tools such as 'fetch-apify-docs' that enable agents to access Apify documentation, platform guides, and best practices without external API calls. These tools are implemented as internal type tools within the MCP server, allowing agents to self-serve documentation lookups and troubleshoot issues autonomously.

Manages session state across multiple MCP tool invocations, enabling multi-turn workflows where agents maintain context about previous operations, selected Actors, and execution history. The server tracks session metadata, task history, and user preferences, allowing agents to reference prior decisions and results without re-querying or re-executing.

Provides a built-in 'search-actors' internal tool that queries the Apify Store to discover Actors matching user intent, with semantic filtering based on descriptions, tags, and categories. The tool integrates with the Apify API to retrieve Actor metadata, schemas, and pricing information, enabling AI agents to autonomously select appropriate scrapers/crawlers for data extraction tasks without manual tool selection.

Manages asynchronous execution of long-running Actors through a task storage system that tracks in-flight operations, polls for completion status, and retrieves results without blocking the MCP client. The server maintains a task registry (likely in-memory or persistent storage) that maps task IDs to Actor run metadata, enabling clients to check status and fetch results via separate MCP tool calls rather than waiting for synchronous completion.

Transforms Apify Actor input schemas into MCP-compliant tool schemas through schema processing logic that handles type mapping, constraint validation, and widget generation. The server parses Actor JSON schemas, applies transformations to match MCP expectations, and generates UI widgets (for OpenAI mode) that guide users through complex input parameters. This enables type-safe invocation of Actors with heterogeneous input requirements.

Enables the Apify MCP server to proxy tools from other MCP servers that have been 'Actorized' (wrapped as Apify Actors), exposing them as actor-mcp type tools. This creates a composable MCP ecosystem where tools from external MCP servers can be discovered and invoked through the Apify server without direct client-to-server connections, enabling tool chaining and multi-server orchestration.

Collects telemetry data on tool invocations, execution times, error rates, and user behavior through instrumentation in the ActorsMcpServer class. The server tracks metrics such as which Actors are used, how often, execution duration, and failure modes, enabling monitoring, debugging, and usage analytics without requiring external observability infrastructure.

Provides an OpenAI-compatible mode that generates interactive UI widgets for tool configuration, enabling non-technical users to configure complex Actor parameters through a web interface rather than JSON. The server generates widget definitions (Actor Search Widget, Actor Run Widget) that guide users through tool selection and parameter configuration, with real-time validation and preview capabilities.

Integrates with the Apify API for Actor execution, metadata retrieval, and dataset access through authenticated HTTP requests using API tokens. The server handles authentication, manages API rate limits, and provides error handling for API failures, enabling seamless access to Apify's platform capabilities without exposing API complexity to MCP clients.

Implements a caching layer for frequently accessed data such as Actor metadata, search results, and execution results to reduce API calls and improve response latency. The cache stores Actor definitions, schema transformations, and dataset results with configurable TTL, enabling fast tool discovery and result retrieval without repeated API requests.