Connect the OpenAI Agents SDK to an Apify Actor

Install openai-agents, open MCPServerStreamableHttp with the scoped URL https://mcp.apify.com/?tools=fetch-actor-details,owner/name and an Authorization: Bearer header with your Apify token, and pass the server to Agent(mcp_servers=[...]). The agent sees that Actor's tool plus fetch-actor-details.

Route: Apify MCP server. Install: pip install openai-agents

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: pip install openai-agents

Google Maps

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="Apify",
        params={
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/google-maps-business-lead-finder-with-email",
            "headers": {"Authorization": f"Bearer {os.environ['APIFY_TOKEN']}"},
            "timeout": 120,
        },
        cache_tools_list=True,
    ) as server:
        tools = await server.list_tools()
        print("tools:", [t.name for t in tools])
        agent = Agent(name="Assistant", instructions="Use the Apify tools to get live data.", mcp_servers=[server])
        result = await Runner.run(agent, "Use Google Maps Business Lead Finder with Email & Social Links to get a few records and summarise what came back, with links.")
        print(result.final_output)


asyncio.run(main())

Good to know

  • The package is openai-agents (imported as agents), per OpenAI's own install instructions.
  • Raise params["timeout"] for Actors that take minutes; cache_tools_list=True avoids listing tools on every turn.
  • Scoping the URL with ?tools= keeps the tool list short; without it the agent gets Apify's default tool set.

Actors to start with

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

Sources