Repository navigation
feat!: Split MCP calls out of call-actor - #1685
Conversation
Both definition readers took `webServerMcpPath` from the default build, but Actor Standby can serve a different build. `getActorDefinition` and `fetchActorDetails` now resolve `actorStandby.build` (a tag through `taggedBuilds`, or a build number by scanning the build list newest first) and read `webServerMcpPath` and `webServerSchema` only from that build; the input schema and README stay on the default build. An unresolved build yields no server fields instead of the default build's. The pruned definition gains `hasWebServerSchema`; the schema itself stays out of the cache. `getActorMCPServerURL` resolves against the Actor's `standbyUrl` from the API instead of a constructed hostname. Part of #1620. Closes #1642. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
…ring Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
`resolveActorInterfaces` returns `{ input, mcp, server }`; `resolveActorToolMode`
derives the tool slot from the set exactly as before, so tool loading and
`call-actor` keep their behavior. `getActorToolResolutionCached` returns the set
as `interfaces` next to `toolMode` for the server-interface tools to gate on.
Renames the "no interface" mode and its error: `ACTOR_TOOL_MODE.STANDBY_WITHOUT_MCP`
to `SERVER_ACTOR_WITHOUT_MCP`, `ACTOR_LOAD_ERROR_KIND.STANDBY_WITHOUT_MCP_NOT_SUPPORTED`
to `SERVER_ACTOR_WITHOUT_MCP_NOT_SUPPORTED` (`server-actor-without-mcp-not-supported`),
and `ActorLoadError.standbyWithoutMcpNotSupported` to `serverActorWithoutMcpNotSupported`.
Rejection text is unchanged.
Part of #1620. Closes #1643.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
…rows Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
…build The platform starts a standby run without a build option in that case, which resolves to the Actor's default build, so the readers do the same instead of treating the unset reference as unresolved. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
…sting Listing an Actor's builds needs a token while the Actor and build reads do not, so a token-less session on an Actor whose Standby names an untagged build number failed with a 401 instead of the standby rejection it got before. The tagged builds carry build numbers, so match those first; without a token an untagged build number stays unresolved. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
One HTTP request to a Server Actor's API, the server interface its API schema documents. The tool gates on the `server` interface, resolves the path against the Actor's standbyUrl and refuses one that leaves that origin, and sends once through sendApifyApiRequest: raw response bytes, no redirects, the MAX_INLINE_BYTES cap after decompression and the 120-second deadline. Tools now declare the payment-provider standby check instead of the engine naming them. Response telemetry carries http_status and actor_tenancy. Closes #1623 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCWuvzJDFm6RcTn8XUcFuZ
The default output carries one line for every Server Actor: tenancy, the number of documented operations and how to expand it. output.serverInterface: true lists the operations with the Actor's standbyUrl as the base URL and the cost of its tenancy; "METHOD /path" renders one operation with its local $ref references resolved, keeping circular, missing and external ones with a note. The send tool's description points at the option when the session has the details tool. Closes #1645 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCWuvzJDFm6RcTn8XUcFuZ
A shared, non-circular reference was expanded on every occurrence, so a small chained schema grew exponentially and blocked the event loop. Expansion now stops at MAX_INLINE_BYTES of expanded detail, keeping the rest as references with a note; the required-input list resolves one level only. Path-level parameters count for every operation under the path. Staff review findings. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCWuvzJDFm6RcTn8XUcFuZ
Query parameters are appended after the query written into the path without re-encoding it. A timeout after the headers arrived reports the received status. The Location header is masked like the body. Staff review findings. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCWuvzJDFm6RcTn8XUcFuZ
Reuse `BuildListItem` from the build-list tool, drop the unread `ActorDetailsResult.webServerMcpPath`, and keep the standby build resolution cases in one test file; the details reader keeps its wiring, unresolved and error cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…er requests `resolveOnStandbyOrigin` resolves a path against the Actor's `standbyUrl` and flags a path that leaves that origin. `getActorMCPServerURL` and `send-server-actor-request` both use it; each keeps its own messages and its own rule for credentials in the path. Behavior is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`executeSendServerActorRequest` already passes the deadline down, so `fetchServerActorResponse` takes it as required. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…0b1sxl-1645 # Conflicts: # src/tools/actors/actor_definition.ts
`hasWebServerSchema` and the server-interface section both read
`listServerOperations`, which moves next to the definition loader so the
loader no longer imports from the section formatter. A path item whose
method key holds no operation object (`{ get: null }`) now counts as no
operation in both places.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ndered The widget and a selective `output` without the server interface skip the standby build read. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Node's URLSearchParams typings accept only [string, string] pairs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Apify API spec index and the server-interface section now share `resolveLocalRefs` and `resolveLocalRef` in `apify_api_spec.ts`: RFC 6901 pointers (`~1`, `~0`, array indexes), circular, missing and external references kept with a note, and a `MAX_INLINE_BYTES` expansion cap. The spec index drops examples and vendor extensions as a separate step. The index built from the published Apify API spec is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`readBodyUnderCap` in `apify_client.ts`, next to `sendApifyApiRequest`, reads a streamed body and returns `undefined` past `MAX_INLINE_BYTES`. `resources/read` and `send-server-actor-request` both use it, and `isMaxContentLengthAbort` moves there too, so the tool no longer imports the stream helpers from `resources/`. Behavior is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0129gaZQ8oZYR5zBQMuiSCmQ
…o claude/gifted-planck-0b1sxl-1645
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
The stack was squash-merged, so this applies the PR's changes since the last merged base (8b0845a, identical to #1682 on master) onto master. #1703 moves send-server-actor-request out of the default actors tools; call-actor-mcp-tool stays in them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
send-server-actor-request is served only when selected by name since #1703; fetch-actor-mcp-tool-list stays a default actors tool. The #1703 description test now expects the default line without mcpTools. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
MQ37
left a comment
There was a problem hiding this comment.
Approving, with three things to fix before merging.
Tested at 5eaac4d in podman: type-check, lint, unit suite (3456 passed) and the tools over MCP stdio against a mock API and a mock Actor MCP server.
-
call_actor_mcp_tool.ts:32:toolhas no max length. A 100,000-char name returns a 200 KB error and a 100 KB log line. Add.max(128). -
apify_errors.ts:71:remoteMcpFailureDetailadds "The MCP server may be temporarily unavailable." to every failure, also when the server answered (a wrongtoolgivesMCP error -32602: … Tool subtract not found.plus that sentence). Add it only forConnectionClosed,RequestTimeoutand network errors. -
remote_tool_call.ts:26: on the 120 s timeoutclose()aborts thenotifications/cancelledPOST the SDK just sent, so the remote keeps running. The abort path already yields a macrotask for this; do the same on the timeout path.
- Cap the tool argument at the MCP spec's 128 characters, so an oversized name is rejected before any connection instead of echoed in errors and logs. - Add "The MCP server may be temporarily unavailable." only when the connection closed, the request timed out or the network failed, not when the server answered with an error. - Yield a macrotask before close() on every failed call, so the SDK's notifications/cancelled reaches the server on a timeout as it does on an abort. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
Brings in 903a242: the 128-character tool name cap, the availability hint only for unavailable servers, and the cancel on timeout, which fetch-actor-mcp-tool-list shares through the same wrapper. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f # Conflicts: # tests/unit/tools.actor_mcp_server.test.ts
|
@MQ37 all three are in 903a242:
#1686 has these through the merge in 6386760; its shared test checks the timeout cancel for Generated by Claude Code |
The SDK transports put the HTTP status in the error's numeric code, so a 502/503 during a tool call was echoed without the "temporarily unavailable" hint. Protocol error codes are negative, so a JSON-RPC error still gets none. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
Generated by Claude Code |
Closes #1644. Part of #1620. Stacked on #1685. Listing MCP tools could wake a billed standby run inside the otherwise static `fetch-actor-details`. Explicit discovery separates those operations and returns usable tool definitions. **Breaking:** replace `fetch-actor-details` with `output: {"mcpTools":true}` with: ```text fetch-actor-mcp-tool-list {"actor":"apify/example-mcp-server"} ``` The new default tool returns remote definitions in `structuredContent.tools`, plus compact text with each tool's name, description, and input schema. Discovery is uncached, uses the caller's token, follows all pages, and fails without partial results if a page fails, the agreed 100-page limit is exceeded, or all pages together take longer than the 120-second tool-call timeout. Payment-provider (x402, Skyfire) sessions are not served `fetch-actor-mcp-tool-list`, as with `call-actor-mcp-tool`; a call is still rejected. fetch-actor-details makes no MCP connections. Its old flag and `structuredContent.mcpTools` are removed. An older request containing only `output.mcpTools` gets the default details sections. Hosted migration: [internal #871](apify/apify-mcp-server-internal#871). Existing eval migrations: #1687. ## Notes for reviewers (human-written) This issue looks big, but mostly it contains tests AI-assisted implementation and review with Claude Code and Codex. --------- Co-authored-by: Claude <noreply@anthropic.com>
Refs #1322. This drops the setup video dependency and points the README to [mcp.apify.com](https://mcp.apify.com) and the [MCP docs](https://docs.apify.com/mcp), as the issue proposes. ## What changed The README is reorganized around someone who wants to connect an agent. Setup comes first and contributor material last. The file goes from 608 to 480 lines, and long reference material (input-schema rules, backward compatibility, per-client setup) sits in collapsed sections. - **Top of the page:** a new full-width header image, a "Get config" button for the configurator, and three badge rows (package, CI/license, stars/Discord). Below them are a text H1, a one-sentence definition, the approved "MCP and agent directories" company boilerplate, and one paragraph on how the agent uses the server. - **Setup:** a hosted quickstart, then per-client setup in collapsible blocks. The order is Claude Code, ChatGPT, Cursor, VS Code and GitHub Copilot, Claude, generic JSON, and local stdio. The syntax comes from the configurator, the plugin docs, and `apify mcp install`. The ChatGPT steps follow the new Plugins flow from the internal mcp.apify.com update. - **Remote (hosted) or local MCP server:** a comparison table, plus `mcp-remote` for stdio-only clients. - **How an agent uses Actors:** search, details, `call-actor`, and `get-dataset-items`. It states that `call-actor` returns the run status and storage IDs, not the items. - **Tools, resources, and prompts:** keeps the helper tools list, the ✅/⚡/✅¹ legend, and the full tool table with the Category column. It includes the MCP server Actor tools (`fetch-actor-mcp-tool-list`, `call-actor-mcp-tool`) and `send-server-actor-request` from #1685 and #1686. Tool annotations and prompts/resources are short subsections. Tool selection and UI mode configuration follow, with the backward-compatibility notes in a collapsible block. - **Example prompts:** a use-case table (web research, search and fetch, SERP, Google Maps leads, LinkedIn, reviews, Instagram, TikTok, Amazon, RAG crawling), each row with the Actor the agent typically picks. - **New sections:** - Pricing and limits, with agentic payments as a short callout. - A FAQ, including "What is an MCP server?" and a Playwright MCP comparison. - **Kept:** Telemetry (with Sentry, the `_useCase` field, and the opt-out flags), troubleshooting with the input-schema processing rules, development, contributing, privacy, license, and learn more (which now also holds the links to Apify docs for agents). - **Removed:** the SSE migration notice and text that repeated other sections. Headings and FAQ wording follow keyword research on what people search around MCP servers. Examples are "mcp server", "what is an mcp server", "claude mcp", "claude connectors", "remote mcp server", and "playwright mcp". ## Corrections to the current README - **CI badge:** points at `on_master.yaml`, because `check.yaml` is disabled. The Smithery badge is removed (it returns 500). - **Docs links:** `/platform/integrations/...` links that redirect now use their current URLs. - **UI mode:** documents `auto` as the default, resolved from client capabilities, and that UI mode adds separate `*-widget` tools next to the base tools. - **Limits:** the hosted rate limit is 20 requests per second. Spending caps depend on the pricing model (`maxTotalChargeUsd` for pay-per-event, `maxItems` for pay-per-result). Full-permission Actors need a one-time approval rather than being excluded. Search returns only free and pay-per-event Actors. - **Input schemas:** only prefill and default values are copied into descriptions, not enums. - **Agentic payments:** only AGI is advertised. It accepts x402, MPP, and Skyfire. The direct `payment=x402` and `payment=skyfire` routes are being deprecated, so the README no longer documents them. The dead Skyfire SSE URL and the `mcpc x402` walkthrough are gone. The docs stay the source of truth for payment terms. - **Rental Actors:** the old text said the hosted server offers them, but `search-actors` excludes them on hosted and local alike. - **Local dev server:** `pnpm run dev` with the token in a header replaces `apify run -p`. - **Proxied MCP tools:** names follow the code (`username--actor-name--tool-name`), and `call-actor` addresses them as `actorName:toolName`. ## Default Actors The tool table lists the defaults from `src/const.ts` on master: RAG Web Browser and Web Fetch. Web Search is presented as Web Fetch's pair in the examples and the diagram, since it is set to become the default. When it does, the intro sentence of the tools section and two table rows need updating. ## Example prompt Actors Most rows use Actors maintained by Apify (`apify/`, `compass/`, `clockworks/`, `junglee/`). Two use cases deliberately point to popular community Actors, because they have no Apify-maintained option: X (`apidojo/tweet-scraper`) and LinkedIn (`harvestapi/*`). Every example Actor is free or pay-per-event, so `search-actors` can find it. Flag them if you'd rather keep the README to Apify-maintained Actors. ## Images - `docs/apify-mcp-server-header.png` is a new full-width header in the Apify event design style. It replaces the old light/dark logo pair. - `docs/apify-mcp-server-diagram.png` is a new architecture diagram in the Apify design system. It replaces `docs/apify-mcp-server.png`. - `docs/mcp-configurator.png` is a current screenshot of the mcp.apify.com client setup. It replaces `docs/mcp-clients.png`, which listed clients the configurator no longer offers. - The old image files stay in the repo in case anything outside the README hotlinks them. - A setup video placeholder is left as an HTML comment until a new video exists. ## Overlap with #1329 #1329, from an external contributor, makes five changes. Here is how each lands in this PR: | #1329 change | In this PR | | :--- | :--- | | Smithery badge removed | Same | | Docs link to docs.apify.com/mcp | Same | | CI badge pointing at `check.yaml` | `on_master.yaml` instead, since `check.yaml` is disabled | | Proxied tool names `<actor-tool>__<tool-name>` | Corrected to the format in `src/mcp/proxy.ts` | | Invalid input returns the schema | Kept, scoped to `call-actor` (direct Actor tools don't echo the schema) | Thanks to the #1329 author for the first three fixes. ## Not shipped, so not claimed MCP Tasks (#1119) and elicitations (#184). The Server Actor and MCP tool changes from #1685 and #1686 are documented because they are on master, although they are not in an npm release yet. The `tasks` category is described as saved Actor tasks. ## AI disclosure Drafted with Claude Code. Factual claims were checked against `master`, the published npm package, docs.apify.com, agi.apify.com, and the live configurator. Links were checked. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Why
Closes #1624. Part of #1620.
call-actormixed Actor runs with MCP tool calls and returned.MCP calls now have their own default tool,
call-actor-mcp-tool.Breaking:
call-actorand its widget no longer call MCP tools.Before:
After (returns the remote MCP result unchanged, no run fields):
The old form now answers:
The old syntax is rejected before Actor or payment metadata lookup, including in the widget. The replacement is named only when the session has it. Bare MCP-server Actor identifiers are also rejected by
call-actor.x402 and Skyfire sessions are not served
call-actor-mcp-tool. Their existing standby rejection no longer carries internal telemetry on the wire.Hosted verification (internal #871) and eval migration (#1687) remain release requirements.
AI-assisted implementation and review with Claude Code and Codex.