Model Context Protocol (MCP) is transforming and simplifying how AI applications connect with external tools. While we’ve covered how to use MCP with tools that give agents context from the web, this guide digs deeper into the developer side: how to build and deploy your own MCP servers on the Apify platform.
With Apify's MCP templates, you can transform any stdio or remote MCP server into a scalable, cloud-hosted service in minutes. There are currently two templates available: for Python and for TypeScript.
In this tutorial, we'll show you how to build an MCP server on Apify with TypeScript.
Why deploy MCP servers on Apify?
Before we get into implementation, here’s why the Apify platform is ideal for hosting MCP servers:
- 1. Instant scalability: Apify's infrastructure automatically scales based on demand, from a single request to thousands of concurrent connections.
- 2. Built-in monetization: With the pay-per-event (PPE) model, you can charge users for each tool request, API call, or custom event, turning your MCP server into a revenue stream.
- 3. Persistent URLs: Standby mode provides stable endpoints like
https://your-username--your-mcp-server.apify.actor/mcp, perfect for MCP client configurations. - 4. Zero infrastructure management: No servers to maintain, no Docker orchestration, no SSL certificates. Just deploy and run.
Understanding the architecture
When you deploy an MCP server on Apify, you can work with three types of MCP servers:
- stdio MCP servers: Local servers that communicate via standard input/output, which Apify converts to HTTP for remote access.
- Streamable HTTP MCP servers: Remote servers that already communicate via streamable HTTP, which Apify can proxy and enhance with monetization features.
- Legacy SSE MCP servers: Remote servers that already communicate via Legacy SSE over HTTP, which Apify can proxy and enhance with monetization features.
This flexible architecture allows you to turn any type of MCP server into an Apify Actor, whether it's a local stdio-based tool or a remote MCP endpoint, and expose it through a unified HTTP interface with built-in scaling and monetization.
Step-by-step implementation
Let’s walk through building an MCP server on Apify using the TypeScript template.
Step 1: Choose and create your Actor from the template
# Create the TypeScript MCP server from template
apify create my-mcp-server --template ts-mcp-server
cd my-mcp-serverStep 2: Configure your MCP server
Open src/main.ts and set the MCP_COMMAND:
// For stdio servers:
// Example: Everything MCP server
const MCP_COMMAND = [
'npx',
'@modelcontextprotocol/server-everything',
];
// For remote HTTP servers (requires mcp-remote package):
// Custom MCP endpoint
const MCP_COMMAND = [
'npx',
'mcp-remote',
'https://mcp.apify.com/',
'--header',
'Authorization: Bearer TOKEN',
];Step 3: Install your MCP server dependencies
Update package.json with the MCP server dependencies:
{
"dependencies": {
"@modelcontextprotocol/server-everything": "^2025.5.12",
"mcp-remote": "^0.1.16"
}
}
npm install instead of editing package.json directly.Step 4: Set up monetization (optional)
In .actor/pay_per_event.json:
[
{
"tool-request": {
"eventTitle": "Tool Request",
"eventDescription": "Charge for each tool execution",
"eventPriceUsd": 0.05
}
}
]Trigger charges in your code:
For TypeScript:
await Actor.charge({ eventName: 'tool-request' })
Step 5: Configure Actor settings
We need to configure the webServerMcpPath in .actor/actor.json so the Apify MCP recognizes the Actor as an MCP server. This is the path of the streamable HTTP MCP endpoint exposed by the standby Actor:
{
"actorSpecification": 1,
"name": "my-mcp-server",
"version": "1.0.0",
"usesStandbyMode": true,
"minMemoryMbytes": 512,
"maxMemoryMbytes": 4096,
"webServerMcpPath": "/sse" // So the Actor is recognized as an MCP server
}
Step 6: Deploy to Apify
apify login
apify push
Step 7: Configure standby mode
In Apify Console:
- Go to your Actor’s settings
- Enable “Standby mode”
- Set idle timeout (e.g., 300 seconds)
- Adjust memory allocation as needed
Step 8: Connect your MCP client
Use this URL:
https://your-username--my-mcp-server.apify.actor/mcp
Configure your client by pointing your MCP client to the URL, and be sure to set the Authorization headers with the bearer auth token Authorization: Bearer your-token.
Advanced configuration
Environment variables
To set non-sensitive environment variables, use actor.json:
{
"environmentVariables": {
"RATE_LIMIT": "100"
}
}actor.json file. Instead, set sensitive environment variables in the Apify Console UI under your Actor's settings when doing the build. For more information on setting custom environment variables, see the documentation.TypeScript template capabilities
The TypeScript template supports both stdio and SSE server types:
- Streamable HTTP servers: Remote server proxying using mcp-remote for connecting to external MCP endpoints
- Legacy SSE servers: Remote server proxying using mcp-remote for connecting to external SSE endpoints
Debugging and monitoring
Local development
To run the MCP server locally, use the following command:
APIFY_META_ORIGIN="STANDBY" ACTOR_WEB_SERVER_PORT=8080 apify runYou can use the MCP inspector on GitHub for debugging and testing locally.
Production monitoring
- View Actor logs in Apify Console
- Set up error/usage alerts
- Track monetization in Analytics
Troubleshooting common issues
- Memory errors: Increase memory or optimize code
- Auth failures: Check tokens
What next?
- Add more tools
- Integrate with Apify Actors
- Build custom clients
- Share your server on Apify Store
Conclusion
Deploying MCP servers on the Apify platform turns local tools into scalable, monetizable cloud services. With our TypeScript template and standby mode, you can get a production-ready server running in minutes, whether it's a local stdio server, streamable HTTP, or an existing legacy SSE server.
Explore what’s possible:
