docs: add MCP servers guide

README.md

@@ -117,7 +117,7 @@ Almost any Python project can become an Actor, including projects for:
 - **Browser automation** — Drive a real browser with [Playwright](https://docs.apify.com/sdk/python/docs/guides/playwright) or [Selenium](https://docs.apify.com/sdk/python/docs/guides/selenium), or with higher-level tools such as [Browser Use](https://docs.apify.com/sdk/python/docs/guides/browser-use).
 - **Web servers and APIs** — Run a [web server](https://docs.apify.com/sdk/python/docs/guides/running-webserver) inside an Actor to serve HTTP requests, for example to expose your scraper as a live API.
 - **AI agents** — Host agents built with your framework of choice. Ready-made Actor templates cover [PydanticAI](https://apify.com/templates/python-pydanticai), [CrewAI](https://apify.com/templates/python-crewai), [LangGraph](https://apify.com/templates/python-langgraph), [LlamaIndex](https://apify.com/templates/python-llamaindex-agent), and [Smolagents](https://apify.com/templates/python-smolagents).
-- **MCP servers** — Deploy a Python MCP server as an Actor and make its tools available to any MCP client. See [MCP server](https://apify.com/templates/python-mcp-empty) and [MCP proxy](https://apify.com/templates/python-mcp-proxy) templates
+- **MCP servers** — Deploy a Python MCP server as an Actor and make its tools available to any MCP client (see the [MCP servers guide](https://docs.apify.com/sdk/python/docs/guides/mcp-servers)). Ready-made Actor templates cover the [MCP server](https://apify.com/templates/python-mcp-empty) and [MCP proxy](https://apify.com/templates/python-mcp-proxy).
 
 Whatever you build, the Apify SDK doesn't lock you into a particular framework. Bring the libraries you already use, and let Apify run your project in the cloud.
 
@@ -199,7 +199,7 @@ The full SDK documentation lives at **[docs.apify.com/sdk/python](https://docs.a
 | [Overview](https://docs.apify.com/sdk/python/docs/overview) | What the SDK is, what Actors are, and how the pieces fit together. |
 | [Quick start](https://docs.apify.com/sdk/python/docs/quick-start) | Create, run, and deploy your first Python Actor. |
 | [Concepts](https://docs.apify.com/sdk/python/docs/concepts/actor-lifecycle) | Actor lifecycle, input, storages, events, proxy management, interacting with other Actors, webhooks, accessing the Apify API, logging, configuration, and pay-per-event. |
-| [Guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx) | Integrations with BeautifulSoup, Parsel, Playwright, Selenium, Crawlee, Scrapy, Scrapling, Crawl4AI, and Browser Use, plus running a web server and using uv. |
+| [Guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx) | Integrations with BeautifulSoup, Parsel, Playwright, Selenium, Crawlee, Scrapy, Scrapling, Crawl4AI, and Browser Use, plus building MCP servers, running a web server, validating input with Pydantic, and using uv. |
 | [Upgrading](https://docs.apify.com/sdk/python/docs/upgrading/upgrading-to-v4) | Migrating between major versions. |
 | [API reference](https://docs.apify.com/sdk/python/reference) | Generated reference for every class and method. |
 | [Changelog](https://docs.apify.com/sdk/python/docs/changelog) | Release history and breaking changes. |

docs/01_introduction/index.mdx

@@ -42,7 +42,7 @@ Almost any Python project can become an Actor, including projects for:
 - **Browser automation** - Drive a real browser with [Playwright](./guides/playwright) or [Selenium](./guides/selenium), or with higher-level tools such as [Browser Use](./guides/browser-use).
 - **Web servers and APIs** - Run a [web server](./guides/running-webserver) inside an Actor to serve HTTP requests, for example to expose your scraper as a live API.
 - **AI agents** - Host agents built with your framework of choice. Ready-made Actor templates cover [PydanticAI](https://apify.com/templates/python-pydanticai), [CrewAI](https://apify.com/templates/python-crewai), [LangGraph](https://apify.com/templates/python-langgraph), [LlamaIndex](https://apify.com/templates/python-llamaindex-agent), and [Smolagents](https://apify.com/templates/python-smolagents).
-- **MCP servers** - Deploy a Python MCP server as an Actor and make its tools available to any MCP client. See the [MCP server](https://apify.com/templates/python-mcp-empty) and [MCP proxy](https://apify.com/templates/python-mcp-proxy) templates.
+- **MCP servers** - Deploy a Python MCP server as an Actor and make its tools available to any MCP client (see the [MCP servers guide](./guides/mcp-servers)). Ready-made Actor templates cover the [MCP server](https://apify.com/templates/python-mcp-empty) and [MCP proxy](https://apify.com/templates/python-mcp-proxy).
 
 Whatever you build, the Apify SDK doesn't lock you into a particular framework. Bring the libraries you already use, and let Apify run your project in the cloud.
 

docs/01_introduction/quick-start.mdx

@@ -118,3 +118,4 @@ For other aspects of Actor development, explore these guides:
 - [Project management with uv](./guides/uv)
 - [Input validation with Pydantic](./guides/input-validation)
 - [Running a web server](./guides/running-webserver)
+- [Building MCP servers](./guides/mcp-servers)

docs/03_guides/12_running_webserver.mdx

@@ -23,7 +23,7 @@ The URL is available in the following places:
 
 The web server running inside the container must listen at the port defined by the `Actor.configuration.web_server_port` property. When running Actors locally, the port defaults to `4321`, so the web server will be accessible at `http://localhost:4321`.
 
-## Example Actor
+## Using the standard library
 
 The following example shows how to start a simple web server in your Actor, which will respond to every GET request with the number of items that the Actor has processed so far:
 
@@ -52,14 +52,31 @@ Note that:
 
 - `uvicorn.Server(...).serve()` is a coroutine. It runs as an `asyncio` task alongside the Actor's own work instead of blocking it. Setting `server.should_exit = True` triggers a graceful shutdown once the work is done.
 - The server binds to `0.0.0.0` (all interfaces) rather than `localhost`. This makes it reachable through the container URL, not only from inside the container.
-- The same pattern powers an [Actor Standby](#actor-standby) service. Swap the one-off work loop for an Actor that keeps serving requests.
+- The same pattern powers an [Actor Standby](#exposing-it-over-standby) service. Swap the one-off work loop for an Actor that keeps serving requests.
 
-## Actor Standby
+## Exposing it over Standby
 
 The example runs a web server for the duration of a single Actor run. With [Actor Standby](https://docs.apify.com/platform/actors/development/programming-interface/standby), you can instead expose your Actor as an always-ready HTTP API: the platform keeps the Actor running in the background and routes incoming HTTP requests to the web server inside it, spinning up additional instances as the load grows.
 
 From the SDK's perspective, a Standby Actor is built the same way as the web server above. You start an HTTP server listening on the port from `Actor.configuration.web_server_port`. The difference is operational: instead of doing its work once and exiting, a Standby Actor stays up and serves requests. This makes it a good fit for low-latency, on-demand use cases, such as serving scraped data or acting as a microservice.
 
+To enable Standby, set `usesStandbyMode` in the Actor's `.actor/actor.json`:
+
+```json
+{
+    "actorSpecification": 1,
+    "name": "my-standby-server",
+    "usesStandbyMode": true
+}
+```
+
+Deploy the Actor with `apify push`. Once it's running, a client reaches the web server at the Actor's Standby URL, passing an [Apify API token](https://console.apify.com/account/integrations) as a bearer token:
+
+```bash
+curl "https://me--my-standby-server.apify.actor" \
+    -H "Authorization: Bearer <YOUR_APIFY_API_TOKEN>"
+```
+
 To get started, use the [Standby Python template](https://apify.com/templates/python-standby). For details on enabling Standby, request routing, and readiness probes, see the [Actor Standby documentation](https://docs.apify.com/platform/actors/development/programming-interface/standby).
 
 ## Conclusion

docs/03_guides/13_mcp_servers.mdx

@@ -0,0 +1,149 @@
+---
+id: mcp-servers
+title: Deploying MCP servers
+description: Deploy a Python MCP server as an Apify Actor and make its tools available to any MCP client.
+---
+
+import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
+
+import McpServerExample from '!!raw-loader!roa-loader!./code/13_mcp_server.py';
+import McpProxyExample from '!!raw-loader!roa-loader!./code/13_mcp_proxy.py';
+
+In this guide, you'll learn how to deploy a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server as an Apify Actor.
+
+## Introduction
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI applications connect to external tools and data. An MCP server exposes tools, resources, and prompts, and any MCP client (such as Claude or an IDE assistant) can call them. Hosting that server as an Apify Actor turns it into a remote, always-ready service.
+
+Apify Actors are a good fit for MCP servers:
+
+- With [Actor Standby](https://docs.apify.com/platform/actors/development/programming-interface/standby), the platform keeps the Actor running in the background and routes incoming HTTP requests to it, so your server is always ready to answer an MCP client.
+- The platform scales instances with demand, keeps logs, and handles the network, so you don't operate any infrastructure.
+- Every request carries an Apify API token, so the platform authenticates clients for you.
+- Pay-per-event charging lets you monetize the server, for example per tool call.
+
+There are two ways to build one, and Apify maintains a template for each:
+
+- Write a server from scratch with [FastMCP](https://gofastmcp.com/), starting from the [`python-mcp-empty`](https://apify.com/templates/python-mcp-empty) template. See [MCP server](#mcp-server) below.
+- Wrap an existing MCP server (stdio, HTTP, or SSE) with a proxy, starting from the [`python-mcp-proxy`](https://apify.com/templates/python-mcp-proxy) template. See [MCP proxy](#mcp-proxy) below.
+
+Both templates live in the [actor-templates repository](https://github.com/apify/actor-templates) and can be scaffolded with the [Apify CLI](https://docs.apify.com/cli), for example `apify create my-mcp-server --template python-mcp-empty`.
+
+## Before you start
+
+To follow along, install the [Apify CLI](https://docs.apify.com/cli/docs/installation) and log in with `apify login`. Both examples build on [FastMCP](https://gofastmcp.com/) and are served by [uvicorn](https://www.uvicorn.org/), so declare them in your Actor's `requirements.txt` next to the SDK:
+
+```text
+apify
+fastmcp
+uvicorn
+```
+
+## MCP server
+
+Build your own server when you want to expose your own tools and resources. The following Actor runs a small [FastMCP](https://gofastmcp.com/) server that exposes a single `add` tool and an informational resource. It serves the MCP protocol over the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport on the Actor's web server port:
+
+<RunnableCodeBlock className="language-python" language="python">
+    {McpServerExample}
+</RunnableCodeBlock>
+
+Note that:
+
+- A `build_server` helper registers the tools and resources. Add your own with the `@server.tool()` and `@server.resource()` decorators.
+- `server.http_app(transport='streamable-http')` returns an ASGI app that speaks MCP over Streamable HTTP, which [uvicorn](https://www.uvicorn.org/) then serves.
+- The server binds to `Actor.configuration.web_server_port` and `0.0.0.0`, so the platform can route the Actor's container URL to it. Such routing is the same mechanism described in the [Running a web server](./running-webserver) guide.
+- The example serves in the background for a short window so the run finishes on its own. A production Actor keeps serving until the platform shuts it down. With [Standby](#exposing-it-over-standby), shutdown happens automatically once an instance has been idle for a while.
+
+## MCP proxy
+
+If you already have an MCP server, or want to expose a third-party one, you don't need to rewrite it. FastMCP can wrap an existing server and re-expose it over Streamable HTTP, so you put the same always-ready Apify endpoint in front of a server you didn't write. The following Actor proxies a remote MCP server, serving it on its web server port exactly like the server above:
+
+<RunnableCodeBlock className="language-python" language="python">
+    {McpProxyExample}
+</RunnableCodeBlock>
+
+Note that:
+
+- `create_proxy` connects to the upstream server and returns a FastMCP instance, so the rest of the Actor is identical to a server you build yourself.
+- The example wraps a remote URL. To spawn and wrap a local stdio server, pass an `mcpServers` config instead:
+
+    ```python
+    proxy = create_proxy(
+        {'mcpServers': {'arxiv': {'command': 'uv', 'args': ['run', 'arxiv-mcp-server']}}},
+        name='my-mcp-proxy',
+    )
+    ```
+
+- Serving works the same as the server above. You expose it over [Standby](#exposing-it-over-standby) the same way, so clients connect to `<actor-url>/mcp` with a bearer token.
+- To control which tools clients may call, or to charge per call, add a FastMCP [middleware](https://gofastmcp.com/servers/middleware) that hooks `on_list_tools` and `on_call_tool`.
+
+For a batteries-included gateway with a tool whitelist and per-operation charging already wired up, start from the [`python-mcp-proxy`](https://apify.com/templates/python-mcp-proxy) template.
+
+## Exposing it over Standby
+
+Both the server and the proxy listen on the web server port, so you expose either one the same way. To make it an always-ready HTTP API, enable [Actor Standby](https://docs.apify.com/platform/actors/development/programming-interface/standby) and tell the platform where the MCP endpoint lives. Set both in the Actor's `.actor/actor.json`:
+
+```json
+{
+    "actorSpecification": 1,
+    "name": "my-mcp-server",
+    "usesStandbyMode": true,
+    "webServerMcpPath": "/mcp"
+}
+```
+
+Deploy the Actor with `apify push`. Once it's running, an MCP client connects to the Actor's URL using the Streamable HTTP transport, passing an [Apify API token](https://console.apify.com/account/integrations) as a bearer token:
+
+```json
+{
+    "mcpServers": {
+        "my-mcp-server": {
+            "url": "https://me--my-mcp-server.apify.actor/mcp",
+            "headers": {
+                "Authorization": "Bearer <YOUR_APIFY_API_TOKEN>"
+            }
+        }
+    }
+}
+```
+
+## Monetizing with pay-per-event
+
+Both approaches support [pay-per-event charging](../concepts/pay-per-event), so you can cover the cost of running the server or turn it into a paid product. First, define the events in the Actor's `.actor/pay_per_event.json`:
+
+```json
+{
+    "tool-call": {
+        "eventTitle": "Price for completing a tool call",
+        "eventDescription": "Flat fee for completing a tool call.",
+        "eventPriceUsd": 0.05
+    }
+}
+```
+
+Then charge the event from your code when a client calls a tool. The `add` tool from the [server example](#mcp-server) becomes `async` so it can `await` the charge:
+
+```python
+@server.tool()
+async def add(a: float, b: float) -> float:
+    """Add two numbers and return the sum."""
+    await Actor.charge(event_name='tool-call')
+    return a + b
+```
+
+You can charge per tool call, per resource read, or per any other operation. For the full setup, see the [pay-per-event](../concepts/pay-per-event) guide.
+
+## Conclusion
+
+In this guide, you learned how to deploy an MCP server as an Apify Actor. You can now write a server with FastMCP or wrap an existing one with a proxy, expose it over Actor Standby, connect MCP clients to it, and monetize it with pay-per-event. To get started, see the [Actor templates](https://apify.com/templates/categories/python). If you have questions or need assistance, feel free to reach out on our [GitHub](https://github.com/apify/apify-sdk-python) or join our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy building!
+
+## Additional resources
+
+- [Apify templates: MCP server](https://apify.com/templates/python-mcp-empty)
+- [Apify templates: MCP proxy](https://apify.com/templates/python-mcp-proxy)
+- [Apify: actor-templates repository](https://github.com/apify/actor-templates)
+- [Apify: MCP server documentation](https://docs.apify.com/platform/integrations/mcp)
+- [Model Context Protocol: Official documentation](https://modelcontextprotocol.io)
+- [FastMCP: Official documentation](https://gofastmcp.com/)
+- [Apify blog: What is the Model Context Protocol](https://blog.apify.com/what-is-model-context-protocol/)
+- [Apify blog: How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/)

docs/03_guides/code/13_mcp_proxy.py

@@ -0,0 +1,48 @@
+import asyncio
+
+import uvicorn
+from fastmcp.server import create_proxy
+
+from apify import Actor
+
+# The upstream MCP server to expose. Point this at any remote Streamable HTTP or
+# SSE endpoint. To wrap a local stdio server instead, pass `create_proxy` an
+# `mcpServers` config mapping instead of a URL, for example
+# `{'mcpServers': {'my-server': {'command': ..., 'args': [...]}}}`.
+UPSTREAM_URL = 'https://mcp.example.com/mcp'
+
+
+async def main() -> None:
+    async with Actor:
+        # Connect to the upstream server and re-expose it over Streamable HTTP.
+        proxy = create_proxy(UPSTREAM_URL, name='my-mcp-proxy')
+        app = proxy.http_app(transport='streamable-http')
+
+        # Serve it on the platform's web server port, exactly like a server you
+        # build yourself. Binding to 0.0.0.0 makes it reachable through the
+        # Actor's container URL.
+        config = uvicorn.Config(
+            app,
+            host='0.0.0.0',  # noqa: S104
+            port=Actor.configuration.web_server_port,
+        )
+        web_server = uvicorn.Server(config)
+
+        # Run the server in the background.
+        server_task = asyncio.create_task(web_server.serve())
+
+        url = Actor.configuration.web_server_url
+        Actor.log.info(f'MCP proxy is available at {url}/mcp')
+
+        # In production the server runs until the platform shuts the Actor down.
+        # This runnable example instead serves for a short window so the run
+        # finishes on its own.
+        await asyncio.sleep(60)
+
+        # Signal the server to shut down and wait.
+        web_server.should_exit = True
+        await server_task
+
+
+if __name__ == '__main__':
+    asyncio.run(main())