|
| 1 | +--- |
| 2 | +id: mcp-servers |
| 3 | +title: Building MCP servers |
| 4 | +description: Deploy a Python MCP server as an Apify Actor and make its tools available to any MCP client. |
| 5 | +--- |
| 6 | + |
| 7 | +import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; |
| 8 | + |
| 9 | +import McpServerExample from '!!raw-loader!roa-loader!./code/14_mcp_server.py'; |
| 10 | + |
| 11 | +In this guide, you'll learn how to deploy a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server as an Apify Actor. |
| 12 | + |
| 13 | +## Introduction |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +Apify Actors are a good fit for MCP servers: |
| 18 | + |
| 19 | +- 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. |
| 20 | +- The platform scales instances with demand, keeps logs, and handles the network, so you don't operate any infrastructure. |
| 21 | +- Every request carries an Apify API token, so the platform authenticates clients for you. |
| 22 | +- Pay-per-event charging lets you monetize the server, for example per tool call. |
| 23 | + |
| 24 | +There are two ways to build one, and Apify maintains a template for each: |
| 25 | + |
| 26 | +- Write a server from scratch with [FastMCP](https://gofastmcp.com/), starting from the [`python-mcp-empty`](https://apify.com/templates/python-mcp-empty) template. |
| 27 | +- 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. |
| 28 | + |
| 29 | +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`. |
| 30 | + |
| 31 | +## Example MCP server |
| 32 | + |
| 33 | +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: |
| 34 | + |
| 35 | +<RunnableCodeBlock className="language-python" language="python"> |
| 36 | + {McpServerExample} |
| 37 | +</RunnableCodeBlock> |
| 38 | + |
| 39 | +Note that: |
| 40 | + |
| 41 | +- A `build_server` helper registers the tools and resources. Add your own with the `@server.tool()` and `@server.resource()` decorators. |
| 42 | +- `server.http_app(transport='streamable-http')` returns an ASGI app that speaks MCP over Streamable HTTP, which [uvicorn](https://www.uvicorn.org/) then serves. |
| 43 | +- 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. |
| 44 | +- 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. |
| 45 | + |
| 46 | +## Exposing it over Standby |
| 47 | + |
| 48 | +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`: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "actorSpecification": 1, |
| 53 | + "name": "my-mcp-server", |
| 54 | + "usesStandbyMode": true, |
| 55 | + "webServerMcpPath": "/mcp" |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +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: |
| 60 | + |
| 61 | +```json |
| 62 | +{ |
| 63 | + "mcpServers": { |
| 64 | + "my-mcp-server": { |
| 65 | + "url": "https://me--my-mcp-server.apify.actor/mcp", |
| 66 | + "headers": { |
| 67 | + "Authorization": "Bearer <YOUR_APIFY_API_TOKEN>" |
| 68 | + } |
| 69 | + } |
| 70 | + } |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +## Wrapping an existing MCP server |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +It supports three kinds of upstream server. For a local stdio server, the gateway spawns the process: |
| 79 | + |
| 80 | +```python |
| 81 | +from mcp.client.stdio import StdioServerParameters |
| 82 | + |
| 83 | +from .models import ServerType |
| 84 | + |
| 85 | +server_type = ServerType.STDIO |
| 86 | +MCP_SERVER_PARAMS = StdioServerParameters(command='uv', args=['run', 'arxiv-mcp-server']) |
| 87 | +``` |
| 88 | + |
| 89 | +For a remote HTTP or SSE server, it forwards to a URL: |
| 90 | + |
| 91 | +```python |
| 92 | +from .models import RemoteServerParameters, ServerType |
| 93 | + |
| 94 | +server_type = ServerType.HTTP # or ServerType.SSE |
| 95 | +MCP_SERVER_PARAMS = RemoteServerParameters(url='https://mcp.apify.com') |
| 96 | +``` |
| 97 | + |
| 98 | +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. For details, see the template's README. |
| 99 | + |
| 100 | +## Monetizing with pay-per-event |
| 101 | + |
| 102 | +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: |
| 103 | + |
| 104 | +```python |
| 105 | +await Actor.charge('tool-call') |
| 106 | +``` |
| 107 | + |
| 108 | +This lets you charge per tool call, per resource read, or per any other operation, and covers the cost of running the server. |
| 109 | + |
| 110 | +## Conclusion |
| 111 | + |
| 112 | +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! |
| 113 | + |
| 114 | +## Additional resources |
| 115 | + |
| 116 | +- [Apify templates: MCP server](https://apify.com/templates/python-mcp-empty) |
| 117 | +- [Apify templates: MCP proxy](https://apify.com/templates/python-mcp-proxy) |
| 118 | +- [Apify: actor-templates repository](https://github.com/apify/actor-templates) |
| 119 | +- [Apify: MCP server documentation](https://docs.apify.com/platform/integrations/mcp) |
| 120 | +- [Model Context Protocol: Official documentation](https://modelcontextprotocol.io) |
| 121 | +- [FastMCP: Official documentation](https://gofastmcp.com/) |
| 122 | +- [Apify blog: What is the Model Context Protocol](https://blog.apify.com/what-is-model-context-protocol/) |
0 commit comments