Give a Mastra agent an Apify Actor

Install @mastra/core and @mastra/mcp, create an MCPClient with the scoped URL and an Authorization: Bearer header, then give mcp.listTools() to new Agent({ ..., tools }). The agent can call the Actor; set the client timeout to minutes for long runs. Checked 2026-11-12.

Route: Apify MCP server. Install: npm install @mastra/core @mastra/mcp

Working snippets

Each one is run against the current package before the site publishes it (with a stub Apify API, so nothing is billed). Every Actor page has the same snippet for its own Actor and input, under "In an agent framework".

Install: npm install @mastra/core @mastra/mcp

Google Maps

import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    apify: {
      url: new URL("https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email"),
      requestInit: { headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` } },
    },
  },
  timeout: 300_000, // Actor runs can take minutes
});
const tools = await mcp.listTools();
console.log("tools:", Object.keys(tools));

const agent = new Agent({ id: "apify-agent", name: "Apify agent", instructions: "Use the Apify tools to get live data.", model: "openai/gpt-4o-mini", tools });
const result = await agent.generate("Use Google Maps Business Lead Finder with Email & Social Links to get a few records and summarise what came back, with links.");
console.log(result.text);
await mcp.disconnect();

Good to know

  • Apify's page shows the older MastraMCPClient; current @mastra/mcp exports MCPClient with a servers map and listTools(), which the snippets use.
  • Tool names are namespaced by server (apify_...), so several MCP servers can share one agent.
  • Call mcp.disconnect() when the script ends.

Actors to start with

Every website's Actors · New Actors this month

Other frameworks

Troubleshooting

Why does the client say Unauthorized or invalid token?

Every Apify Actor tool needs a signed-in Apify account. Reconnect the server so the OAuth sign-in runs again, or switch to the token variant: an Authorization: Bearer header with an API token from Apify Console, Settings, API and integrations. For a local server the token must be in the server's own env block, not only in your shell.

Source: Apify MCP server README. This fix on its own page

Why did my agent's tool list change after an update?

Without a tools parameter Apify's server loads its default tool set, which changes between releases. The URLs on this site pin the tools with ?tools=, so the agent always gets the same Actor tool plus fetch-actor-details. Apify's README gives the same advice for production.

Source: Apify MCP server README. This fix on its own page

What happens when the agent sends input the Actor rejects?

The server answers with the Actor's input schema, so the agent can fix the arguments and call again. The fetch-actor-details tool in every scoped URL lets it read that schema before the first call.

Source: Apify MCP server README. This fix on its own page

My old config uses mcp.apify.com/sse and stopped working. Why?

Apify retired the SSE transport on 1 April 2026. Use https://mcp.apify.com with the streamable HTTP transport, as every config on this site does.

Source: Apify changelog: MCP improvements. This fix on its own page

Every fix in one place

Sources