@apify/actors-mcp-server

Exposes Apify Actors as MCP tools that Claude and other MCP clients can invoke directly. Implements the Model Context Protocol specification to translate tool-call requests into Apify Actor API calls, handling authentication, payload marshaling, and result streaming back to the client. Uses MCP's standardized tool schema to describe Actor inputs and outputs, enabling seamless integration with LLM-based agents without custom integration code.

Automatically discovers all Actors available in an Apify account and generates MCP-compliant tool schemas describing their inputs, outputs, and execution parameters. Introspects Actor metadata (name, description, input schema, expected output format) from Apify's API and transforms it into MCP ToolDefinition objects that LLM clients can parse and present to users. Caches schema information to avoid repeated API calls during agent planning phases.

Propagates execution context (user ID, session ID, request ID, custom metadata) through Actor invocations, enabling traceability and correlation across distributed executions. Injects context into Actor environment variables and logs, allowing Actors to include context in their output for audit trails. Supports custom metadata tags that agents can attach to Actor runs for filtering and analysis.

Enforces rate limits on Actor invocations to prevent overwhelming Apify infrastructure or exceeding account concurrency limits. Implements token-bucket rate limiting with configurable rates (e.g., max 10 concurrent Actors, max 100 invocations per minute). Queues excess invocations and executes them as capacity becomes available, providing agents with visibility into queue status and estimated wait times.

Streams Actor execution results back to the MCP client in real-time, handling pagination for large datasets and chunking output into manageable pieces. Implements streaming via MCP's text content blocks, allowing long-running Actors to return partial results as they complete. Automatically handles Apify's dataset pagination API, fetching results in batches and presenting them to the client without requiring manual offset/limit management.

Tracks Actor execution state (running, succeeded, failed, timed out) and exposes status information to the MCP client via tool results and optional status callbacks. Polls Apify's Actor run API at configurable intervals to detect completion, failures, and resource constraints. Provides structured error messages including failure reasons, logs, and resource usage metrics that help LLM agents understand why an Actor failed and decide whether to retry or escalate.

Validates Actor input parameters against the Actor's declared input schema before execution, catching configuration errors early and providing detailed validation error messages. Uses JSON schema validation to check required fields, type constraints, and value ranges. Returns validation errors to the LLM client before attempting execution, allowing agents to correct inputs or request user clarification rather than wasting Actor execution time on invalid inputs.

Enables sequential or parallel execution of multiple Actors within a single agent workflow, with output from one Actor automatically passed as input to the next. Implements dependency tracking to ensure Actors execute in the correct order, and provides utilities for transforming output from one Actor into the input format expected by the next. Handles error propagation — if an Actor in a chain fails, subsequent Actors are skipped unless the agent explicitly implements retry logic.

Allows specifying Actor execution parameters including memory allocation, timeout duration, and build version at invocation time. Translates these parameters into Apify Actor run API options, enabling agents to optimize resource usage based on task requirements. Supports memory scaling (256MB to 32GB) and timeout configuration (30 seconds to 24 hours) to handle both lightweight and resource-intensive workloads without requiring separate Actor versions.

Automatically transforms Actor output into standardized formats (JSON, CSV, markdown) suitable for LLM consumption. Handles conversion from Apify's native dataset format into structured JSON, flattens nested objects for readability, and optionally summarizes large result sets into representative samples. Supports custom transformation rules to map Actor-specific output fields into domain-specific schemas that agents understand.

Estimates Actor execution cost before invocation based on memory allocation, timeout, and historical execution patterns. Tracks cumulative costs across multiple Actor runs within a session and provides budget alerts when approaching spending limits. Integrates with Apify's pricing API to fetch current rates and calculate costs in the agent's configured currency. Allows agents to make cost-aware decisions (e.g., skip expensive Actors if budget is depleted).

Implements automatic retry mechanisms for failed Actor executions with configurable backoff strategies (exponential, linear, fixed). Supports fallback Actors — if the primary Actor fails, automatically invoke an alternative Actor with compatible output schema. Tracks retry attempts and provides detailed failure history to help agents understand failure patterns and decide whether to continue retrying or escalate to user.