diff --git a/README.md b/README.md index 56f78840..4511940a 100644 --- a/README.md +++ b/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, 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. | diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx index 133c6a47..fe9d3143 100644 --- a/docs/01_introduction/index.mdx +++ b/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. diff --git a/docs/01_introduction/quick-start.mdx b/docs/01_introduction/quick-start.mdx index 289659bf..0e55342d 100644 --- a/docs/01_introduction/quick-start.mdx +++ b/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) diff --git a/docs/03_guides/14_mcp_servers.mdx b/docs/03_guides/14_mcp_servers.mdx new file mode 100644 index 00000000..14d50dd8 --- /dev/null +++ b/docs/03_guides/14_mcp_servers.mdx @@ -0,0 +1,122 @@ +--- +id: mcp-servers +title: Building 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/14_mcp_server.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) behind a gateway, 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`. + +## 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: + + + {McpServerExample} + + +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. This is the same mechanism described in the [Running a web server](./running-webserver) guide. +- The server keeps running until the platform shuts the Actor down. With Standby, that happens automatically once an instance has been idle for a while. + +### Exposing it over Standby + +To make the server 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" +} +``` + +Once deployed, 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 " + } + } + } +} +``` + +## MCP proxy + +If you already have an MCP server (or want to expose a third-party one), you don't need to rewrite it. The [`python-mcp-proxy`](https://apify.com/templates/python-mcp-proxy) template runs a gateway that connects to an existing server and re-exposes it over Streamable HTTP, while adding Apify's charging and tool authorization on top. + +It supports three kinds of upstream server. For a local stdio server, the gateway spawns the process: + +```python +from mcp.client.stdio import StdioServerParameters + +from .models import ServerType + +server_type = ServerType.STDIO +MCP_SERVER_PARAMS = StdioServerParameters(command='uv', args=['run', 'arxiv-mcp-server']) +``` + +For a remote HTTP or SSE server, it forwards to a URL: + +```python +from .models import RemoteServerParameters, ServerType + +server_type = ServerType.HTTP # or ServerType.SSE +MCP_SERVER_PARAMS = RemoteServerParameters(url='https://mcp.apify.com') +``` + +On top of forwarding requests, the gateway gives you a `TOOL_WHITELIST` to control which tools clients may call, and a hook to charge for each MCP operation. Like a server you build yourself, the proxy runs over [Actor Standby](#exposing-it-over-standby) and clients connect to it the same way. For details, see the template's README. + +## Monetizing with pay-per-event + +Both templates support [pay-per-event charging](../concepts/pay-per-event). You define events such as `tool-call` in the Actor's monetization settings and trigger them from the code when a client calls a tool: + +```python +await Actor.charge('tool-call') +``` + +This lets you charge per tool call, per resource read, or per any other operation, and covers the cost of running the server. + +## 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 the proxy template, 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/) diff --git a/docs/03_guides/code/14_mcp_server.py b/docs/03_guides/code/14_mcp_server.py new file mode 100644 index 00000000..6d9fd3e1 --- /dev/null +++ b/docs/03_guides/code/14_mcp_server.py @@ -0,0 +1,49 @@ +import asyncio + +import uvicorn +from fastmcp import FastMCP + +from apify import Actor + + +def build_server() -> FastMCP: + """Create a FastMCP server exposing one tool and one resource.""" + server = FastMCP(name='calculator') + + @server.tool() + def add(a: float, b: float) -> float: + """Add two numbers and return the sum.""" + return a + b + + @server.resource(uri='resource://calculator/info', name='calculator-info') + def info() -> str: + """Describe what this MCP server does.""" + return 'A simple calculator MCP server that adds two numbers.' + + return server + + +async def main() -> None: + async with Actor: + # Build the server and expose it over the Streamable HTTP transport. + server = build_server() + app = server.http_app(transport='streamable-http') + + # Serve it on the platform's web server port. Binding to 0.0.0.0 makes + # the server reachable through the Actor's container URL. + config = uvicorn.Config( + app, + host='0.0.0.0', # noqa: S104 + port=Actor.configuration.web_server_port, + ) + + url = Actor.configuration.web_server_url + Actor.log.info(f'MCP server is available at {url}/mcp') + + # Keep serving until the platform shuts the Actor down, for example when + # a Standby instance has been idle past its timeout. + await uvicorn.Server(config).serve() + + +if __name__ == '__main__': + asyncio.run(main())