Skip to content

feat!: Split MCP calls out of call-actor - #1685

Merged
jirispilka merged 132 commits into
masterfrom
claude/exciting-volta-kzgq4t
Oct 28, 2026
Merged

jirispilka merged 132 commits into
masterfrom
claude/exciting-volta-kzgq4t

Conversation

@jirispilka

@jirispilka jirispilka commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Closes #1624. Part of #1620.

call-actor mixed Actor runs with MCP tool calls and returned.
MCP calls now have their own default tool, call-actor-mcp-tool.

Breaking: call-actor and its widget no longer call MCP tools.

Before:

call-actor {"actor":"apify/example-mcp-server:add","input":{"firstNumber":2,"secondNumber":3}}

After (returns the remote MCP result unchanged, no run fields):

call-actor-mcp-tool {"actor":"apify/example-mcp-server","tool":"add","arguments":{"firstNumber":2,"secondNumber":3}}

The old form now answers:

The "actor:tool" syntax is no longer supported by call-actor. Use call-actor-mcp-tool with separate actor and tool arguments.

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.

claude and others added 30 commits October 22, 2026 00:51
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
`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
…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
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
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
jirispilka pushed a commit that referenced this pull request Oct 27, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6pji1VghkyFysbxkxpp3f
Base automatically changed from claude/gifted-planck-0b1sxl-1645 to master October 27, 2026 09:14
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
@apify-service-account apify-service-account linked an issue Oct 27, 2026 that may be closed by this pull request
1 of 6 tasks
jirispilka pushed a commit that referenced this pull request Oct 27, 2026
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
@jirispilka
jirispilka marked this pull request as ready for review October 27, 2026 21:09
@apify-service-account apify-service-account added the tested Temporary label used only programatically for some analytics. label Oct 27, 2026
@apify-service-account apify-service-account added the t-ai Issues owned by the AI team. label Oct 27, 2026

@MQ37 MQ37 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

  1. call_actor_mcp_tool.ts:32: tool has no max length. A 100,000-char name returns a 200 KB error and a 100 KB log line. Add .max(128).

  2. apify_errors.ts:71: remoteMcpFailureDetail adds "The MCP server may be temporarily unavailable." to every failure, also when the server answered (a wrong tool gives MCP error -32602: … Tool subtract not found. plus that sentence). Add it only for ConnectionClosed, RequestTimeout and network errors.

  3. remote_tool_call.ts:26: on the 120 s timeout close() aborts the notifications/cancelled POST 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
jirispilka pushed a commit that referenced this pull request Oct 28, 2026
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

Copy link
Copy Markdown
Collaborator Author

@MQ37 all three are in 903a242:

  1. tool is capped at 128 characters (MCP_TOOL_NAME_MAX_LENGTH), so an oversized name is rejected before any connection.
  2. The "temporarily unavailable" sentence is added only for ConnectionClosed, RequestTimeout and network errors (a string system error code, or fetch's TypeError with a cause). A JSON-RPC error the server answered with is echoed without it.
  3. The catch yields a macrotask on every failure, so the notifications/cancelled the SDK sends on a timeout reaches the server before close(). A new test makes a call time out against a local server and checks that the server receives the cancellation; it fails without the fix.

#1686 has these through the merge in 6386760; its shared test checks the timeout cancel for fetch-actor-mcp-tool-list too.


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>
jirispilka added a commit that referenced this pull request Oct 28, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copy link
Copy Markdown
Collaborator Author

Integration tests failed on d41eaf6 in one case, storage > masks the session token via resources/read (stdio): the Apify API answered HTTP 429: You have exceeded the rate limit of 60 requests per second for /v2/browser-info. That is a platform rate limit, not this PR's code (the other 480 cases passed, including the call-actor-mcp-tool and legacy-syntax ones). Re-running the failed job once.


Generated by Claude Code

@jirispilka
jirispilka merged commit 910c297 into master Oct 28, 2026
30 of 31 checks passed
@jirispilka
jirispilka deleted the claude/exciting-volta-kzgq4t branch October 28, 2026 22:04
jirispilka added a commit that referenced this pull request Oct 28, 2026
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>
lukas-bekr added a commit that referenced this pull request Oct 28, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

t-ai Issues owned by the AI team. tested Temporary label used only programatically for some analytics.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Server Actor tools for the server interface and MCP tools feat!: Split MCP calls out of call-actor

5 participants