actors-mcp-server

Official

by apify

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Send Server Actor request

send-server-actor-request

Destructive

Send one HTTP request to an Actor Server’s documented API endpoint, with method, path, query, and JSON body, to fetch results or trigger an Actor run.

Instructions

Send one HTTP request to an Actor Server: the HTTP API of a Server Actor, documented in its API schema (OpenAPI) and README. fetch-actor-details with output.serverInterface returns the documented operations with their parameters. Give the method, the path, and optionally query parameters and a JSON body; the Actor Server's host and your Apify API token are added for you. Only an Actor with an Actor Server and an API schema takes requests here; the Actor accepts or rejects the method and path. A request to a single-tenant Actor Server can start a run of the Actor in your account, kept until its idle timeout; a multi-tenant Actor Server charges per event. The request is sent once, with no retries and without following redirects. A JSON, text, or XML response body is returned as text, cut at 262144 bytes; other content types are not returned.

Example call: {"actor": "apify/rag-web-browser", "method": "GET", "path": "/search", "query": {"query": "AI news", "maxResults": 3}}

USAGE:

Use when the Actor that fits the user's request has an Actor Server, and its API schema or README names the endpoint for the task.
Fits requests for one or a few results returned in the HTTP response. Larger batches depend on the endpoint and the response size and time limits.

USAGE EXAMPLES:

user_input: Search the web for the latest AI news and read the top pages with apify/rag-web-browser
user_input: Read https://docs.apify.com as Markdown with apify/rag-web-browser

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "actor": "<actor>",
      "method": "<method>",
      "path": "<path>"
    },
    "name": "send-server-actor-request"
  }
}

Input Schema

Name	Required	Description
`body`	No	The JSON request body, sent as application/json. Not allowed with GET.
`path`	Yes	The path of an operation in the Actor API schema, starting with /. Take it from the schema; do not guess it. A query string written into the path is sent too.
`actor`	Yes	The Actor: its ID, or its name in the "username/name" form, such as "apify/web-fetch".
`query`	No	Query parameters of the operation, by name. A boolean is sent as true or false, and an array as a repeated parameter (name=a&name=b), or comma-joined (name=a,b) where the operation documents the parameter so. Added to a query string in the path.
`method`	Yes	HTTP method: GET, POST, PUT, PATCH, or DELETE. The Actor accepts or rejects it.

Output Schema

Name	Required	Description
`body`	No	Response body as text; empty when the response had none; its start when truncated; absent when omitted
`path`	Yes	Path sent, with its query
`bytes`	No	Size of the body received in bytes, after decompression
`method`	Yes	HTTP method sent
`reason`	No	Why the response body was omitted
`status`	Yes	HTTP status received
`actorId`	Yes	Actor ID
`summary`	Yes	Readable summary of the HTTP response
`tenancy`	Yes	single-tenant: a run of the Actor in your account served the request; multi-tenant: a run of the Actor's owner did, charged per event
`location`	No	Location header of a redirect, which is not followed
`nextStep`	No	Where to look to correct the request, or why the Actor Server refused it
`actorName`	Yes	Actor full name (username/name)
`interface`	Yes	The Actor interface used: its Actor Server
`bodyOmitted`	No	The response arrived, but its body was not returned
`contentType`	No	Content-Type of the response; absent when it had none
`errorMessage`	No	The error string of a JSON {"error": ...} error body; other error bodies are only in body
`bodyTruncated`	No	The response body is longer than the limit; body holds its start

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.21.4Nov 6, 2026

changedInput schema / properties / query / additionalProperties / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    },
+    "type": "array"
+  }
+]

changedInput schema / properties / query / description

Previous value: -"Query parameters, by name, for example {\"limit\": 10, \"verbose\": true}; a boolean is sent as true or false. Added to a query string in the path."New value: +"Query parameters of the operation, by name. A boolean is sent as true or false, and an array as a repeated parameter (name=a&name=b), or comma-joined (name=a,b) where the operation documents the parameter so. Added to a query string in the path."

changedOutput schema / properties / body / description

Previous value: -"Response body as text; empty when the response had none; absent when omitted"New value: +"Response body as text; empty when the response had none; its start when truncated; absent when omitted"

addedOutput schema / properties / bodyTruncated

Added value: +{
+  "const": true,
+  "description": "The response body is longer than the limit; body holds its start",
+  "type": "boolean"
+}

changedOutput schema / properties / bytes / description

Previous value: -"Response body size in bytes, after decompression; absent when over the limit"New value: +"Size of the body received in bytes, after decompression"

Addedv0.20.1Nov 3, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: no retries, no redirect following, response body truncated at 262144 bytes, and non-JSON/text/XML content types are dropped. It also discloses side-effect models the annotations can't express – a single-tenant server may start a run kept until idle timeout, and a multi-tenant server charges per event – which meaningfully explains the destructive/openWorld hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core purpose, requirements, constraints, and an example are front-loaded and sectioned, so scanning is easy. A few lines, such as the multi-tenant charging note and the truncation detail, are dense but each carries operational weight; nothing is filler, though the block is on the long side.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs for a 5-parameter, open-world request tool: where the path comes from, auth/host injection, retry and redirect behavior, response size and content-type handling, and cost/side-effect implications. Return values are covered by the output schema, so no further description is owed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description still adds real meaning: the path must be taken from the schema rather than guessed, body is disallowed with GET, query arrays serialize as repeated or comma-joined, and a full worked example call is provided. The remaining gaps (e.g. per-parameter limits) are minor given the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Send one HTTP request to an Actor Server,' and immediately scopes it to the Actor's HTTP API as documented in its OpenAPI schema. It is clearly distinguishable from siblings such as call-actor (runs an Actor) and fetch-actor-details (discovers the operations), which it explicitly references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ('Use when the Actor ... has an Actor Server, and its API schema or README names the endpoint') plus a rough scale boundary ('Fits requests for one or a few results ... Larger batches depend on the endpoint and the response size and time limits'). It also points at fetch-actor-details with output.serverInterface as the prerequisite discovery step. It stops short of naming a concrete alternative for large-batch work, leaving that inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server