feat: add mcp starter templates ts-mcp-server and python-mcp-server and rename the proxy ones to ts-mcp-proxy and python-mcp-proxy (#586)

Changes:
- renamed the old mcp servers from `-server` to `-proxy`
- added new starter mcp server templates `ts-mcp-server` and
`python-mcp-server`

---------

Co-authored-by: Jiří Spilka <[email protected]>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: GitHub Actions <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jiri Spilka <[email protected]>

Author: 4 people

Makefile

@@ -21,7 +21,8 @@ type-check:
 	uv run mypy templates/python-crawlee-playwright
 	uv run mypy --ignore-missing-imports templates/python-crawlee-playwright-camoufox
 	uv run mypy templates/python-empty
-	uv run mypy templates/python-mcp-server
+	uv run mypy templates/python-mcp-empty
+	uv run mypy templates/python-mcp-proxy
 	uv run mypy templates/python-playwright
 	uv run mypy templates/python-scrapy
 	uv run mypy templates/python-selenium

pyproject.toml

@@ -94,6 +94,7 @@ warn_unused_ignores = true
 
 [[tool.mypy.overrides]]
 module = [
+    "fastmcp",    # Untyped and/or stubs not available
     "smolagents", # Untyped and/or stubs not available
 ]
 ignore_missing_imports = true

templates/manifest.json

@@ -298,14 +298,14 @@
             "useCases": ["AI"]
         },
         {
-            "id": "python-mcp-server",
-            "name": "python-mcp-server",
-            "label": "Python MCP server",
+            "id": "python-mcp-proxy",
+            "name": "python-mcp-proxy",
+            "label": "Python MCP proxy",
             "category": "python",
             "technologies": ["mcp"],
             "skipTests": true,
             "description": "Demonstrates how to convert a Python stdio, HTTP-streamable, or SSE-based Model Context Protocol server into an Apify Actor.",
-            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/python-mcp-server.zip?raw=true",
+            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/python-mcp-proxy.zip?raw=true",
             "defaultRunOptions": {
                 "build": "latest",
                 "memoryMbytes": 512,
@@ -314,6 +314,23 @@
             "showcaseFiles": ["src/main.py", "src/server.py"],
             "useCases": ["AI"]
         },
+        {
+            "id": "python-mcp-empty",
+            "name": "python-mcp-empty",
+            "label": "Python MCP server",
+            "category": "python",
+            "technologies": ["mcp"],
+            "skipTests": true,
+            "description": "Create a Model Context Protocol server using Python and FastMCP with Apify Actor integration for pay-per-event monetization.",
+            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/python-mcp-empty.zip?raw=true",
+            "defaultRunOptions": {
+                "build": "latest",
+                "memoryMbytes": 512,
+                "timeoutSecs": 60
+            },
+            "showcaseFiles": ["src/main.py"],
+            "useCases": ["AI"]
+        },
         {
             "id": "js-crawlee-cheerio",
             "name": "project_cheerio_crawler_js",
@@ -678,13 +695,13 @@
             "useCases": ["AI"]
         },
         {
-            "id": "ts-mcp-server",
-            "name": "ts-mcp-server",
-            "label": "TypeScript MCP server",
+            "id": "ts-mcp-proxy",
+            "name": "ts-mcp-proxy",
+            "label": "TypeScript MCP proxy",
             "category": "typescript",
             "technologies": ["mcp"],
             "description": "Example of how to turn a Model Context Protocol stdio, HTTP Streamable, or SSE server into an Apify Actor.",
-            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/ts-mcp-server.zip?raw=true",
+            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/ts-mcp-proxy.zip?raw=true",
             "defaultRunOptions": {
                 "build": "latest",
                 "memoryMbytes": 512,
@@ -693,6 +710,22 @@
             "showcaseFiles": ["src/main.ts", "src/billing.ts"],
             "useCases": ["AI"]
         },
+        {
+            "id": "ts-mcp-empty",
+            "name": "ts-mcp-empty",
+            "label": "TypeScript MCP server",
+            "category": "typescript",
+            "technologies": ["mcp"],
+            "description": "Create a Model Context Protocol server using TypeScript and Express with Apify Actor integration for pay-per-event monetization.",
+            "archiveUrl": "https://github.com/apify/actor-templates/blob/master/dist/templates/ts-mcp-empty.zip?raw=true",
+            "defaultRunOptions": {
+                "build": "latest",
+                "memoryMbytes": 512,
+                "timeoutSecs": 600
+            },
+            "showcaseFiles": ["src/main.ts"],
+            "useCases": ["AI"]
+        },
         {
             "id": "cli-start",
             "name": "cli-start",

templates/python-mcp-empty/.actor/actor.json

@@ -0,0 +1,23 @@
+{
+    "actorSpecification": 1,
+    "name": "python-mcp-empty",
+    "title": "Python MCP Server",
+    "description": "Python Model Context Protocol (MCP) server using FastMCP.",
+    "version": "0.0",
+    "buildTag": "latest",
+    "usesStandbyMode": true,
+    "meta": {
+        "templateId": "python-mcp-empty",
+        "generatedBy": "<FILL-IN-MODEL>"
+    },
+    "input": {
+        "title": "Actor input schema",
+        "description": "This is Actor input schema",
+        "type": "object",
+        "schemaVersion": 1,
+        "properties": {},
+        "required": []
+    },
+    "dockerfile": "../Dockerfile",
+    "webServerMcpPath": "/mcp"
+}

templates/python-mcp-empty/.actor/pay_per_event.json

@@ -0,0 +1,7 @@
+{
+    "tool-call": {
+        "eventTitle": "Price for completing a tool call",
+        "eventDescription": "Flat fee for completing a tool call.",
+        "eventPriceUsd": 0.05
+    }
+}

templates/python-mcp-empty/.dockerignore

@@ -0,0 +1,35 @@
+.git
+.mise.toml
+.nvim.lua
+storage
+
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.coverage
+.pytest_cache/
+.env
+.venv
+venv/
+ENV/
+.idea/
+.vscode
+.zed

templates/python-mcp-empty/.gitignore

@@ -0,0 +1,37 @@
+.mise.toml
+mise.toml
+.nvim.lua
+storage
+
+# The rest is copied from https://github.com/github/gitignore/blob/main/Python.gitignore
+
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.coverage
+.pytest_cache/
+.env
+.venv
+venv/
+ENV/
+.idea/
+.vscode
+.zed

templates/python-mcp-server/AGENTS.md templates/python-mcp-empty/AGENTS.mdtemplates/python-mcp-server/AGENTS.md renamed to templates/python-mcp-empty/AGENTS.md

@@ -0,0 +1,81 @@
+## MCP server template
+
+<!-- This is an Apify template readme -->
+
+A template for creating a [Model Context Protocol](https://modelcontextprotocol.io) server using [FastMCP](https://docs.fasitmcp.dev/) on [Apify platform](https://docs.apify.com/platform).
+
+This template includes a simple example MCP server with:
+
+- An `add` tool that adds two numbers together with structured output
+- A dummy `calculator-info` resource endpoint
+- Pay [Per Event monetization](https://docs.apify.com/platform/actors/publishing/monetize#pay-per-event-pricing-model) support
+
+## How to use
+
+1. **Modify the server**: Edit `src/main.py` to add your own tools and resources
+2. **Add new tools**: Use the `@server.tool()` decorator to register new tools
+3. **Add new resources**: Use the `@server.resource()` decorator to register new resources
+4. **Update billing**: Configure billing events in `.actor/pay_per_event.json` and charge for tool calls
+
+The server runs on port 3000 (or APIFY_CONTAINER_PORT if set) and exposes the MCP protocol at the `/mcp` endpoint.
+
+## Running locally
+
+```bash
+pip install -r requirements.txt
+APIFY_META_ORIGIN=STANDBY python -m src
+```
+
+The server will start and listen for MCP requests at `http://localhost:3000/mcp`
+
+## Deploying to Apify
+
+[Push your Actor](https://docs.apify.com/academy/deploying-your-code/deploying) to the Apify platform and configure [standby mode](https://docs.apify.com/platform/actors/development/programming-interface/standby).
+
+Then connect to the Actor endpoint with your MCP client: `https://me--my-mcp-server.apify.actor/mcp` using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http).
+
+**Important:** When connecting to your deployed MCP server, pass your Apify API token in the `Authorization` header as a Bearer token:
+
+```
+Authorization: Bearer <YOUR_APIFY_API_TOKEN>
+```
+
+### Pay per event
+
+This template uses the [Pay Per Event (PPE)](https://docs.apify.com/platform/actors/publishing/monetize#pay-per-event-pricing-model) monetization model, which provides flexible pricing based on defined events.
+
+To charge users, define events in JSON format and save them on the Apify platform. Here is an example schema with the `tool-call` event:
+
+```json
+{
+    "tool-call": {
+        "eventTitle": "Price for completing a tool call",
+        "eventDescription": "Flat fee for completing a tool call.",
+        "eventPriceUsd": 0.05
+    }
+}
+```
+
+In the Actor, trigger the event with:
+
+```python
+await Actor.charge(event_name='tool-call')
+```
+
+This approach allows you to programmatically charge users directly from your Actor, covering the costs of execution and related services.
+
+To set up the PPE model for this Actor:
+
+- **Configure Pay Per Event**: establish the Pay Per Event pricing schema in the Actor's **Monetization settings**. First, set the **Pricing model** to `Pay per event` and add the schema. An example schema can be found in [pay_per_event.json](.actor/pay_per_event.json).
+
+## Resources
+
+- [What is Anthropic's Model Context Protocol?](https://blog.apify.com/what-is-model-context-protocol/)
+- [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/)
+- [FastMCP documentation](https://gofastmcp.com/getting-started/welcome)
+- [Python SDK examples](https://github.com/modelcontextprotocol/python-sdk/tree/main)
+- [Python tutorials in Academy](https://docs.apify.com/academy/python)
+- [Apify SDK documentation](https://docs.apify.com/sdk/python/)
+- [Webinar: Building and monetizing MCP servers on Apify](https://www.youtube.com/watch?v=w3AH3jIrXXo)
+- [Apify MCP server documentation](https://docs.apify.com/platform/integrations/mcp)
+- [Apify MCP server configuration](https://mcp.apify.com/)