Develop a custom MCP server

MCP servers (Model Context Protocol) provide a toolkit of multiple tools—individual capabilities for accessing specific APIs or databases. These servers can be interacted with using WebSocket protocol on the server’s global endpoint. You can develop custom MCP servers in TypeScript or Python and deploy them on Blaxel by integrating a few lines of the Blaxel SDK and leveraging our other developer tools (Blaxel CLI, GitHub action, etc.).

Quickstart

It is required to have npm (TypeScript) or uv (Python) installed to use the following command.

You can quickly initialize a new MCP server from scratch by using CLI command bl create-mcp-server. This will create a pre-scaffolded local repo where your entire code can be added.

bl create-mcp-server my-mcp

You can test it by running the following command which launches both the server and a web application (MCP Inspector, managed by MCP) locally for testing the server’s capabilities during development.


pnpm inspect

The web application is accessible at: http://127.0.0.1:6274. Alternatively, you can just simply serve the server locally by running bl serve --hotreload.

Develop the MCP server logic

Develop in TypeScript

If you open the src/server.ts file, you’ll see the complete server implementation. It follows the MCP server standard, with the only difference being our use of Blaxel transport that leverages WebSockets for efficient platform serving.The main component you’ll need to modify is the tool definition:

server.ts


import { BlaxelMcpServerTransport } from "@blaxel/core";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "mymcp",
  version: "1.0.0",
  description: ""
});

server.tool(
  "hello_world",
  "Say hello to a person",
  {
    firstname: z.string()
  },
  async ({firstname}) => {
    console.info(`Hello world called`);
    return {
      content: [{ type: "text", text: `Hello ${firstname}` }]
    }
  }
);

function main() {
  let transport;
  if (process.env.BL_SERVER_PORT) {
    transport = new BlaxelMcpServerTransport();
  } else {
    transport = new StdioServerTransport();
  }
  server.connect(transport);
  console.info("Server started");
}

main();

Remember that the name, description, and parameters are crucial—they help your agent understand how your tool functions.

Develop in Python

If you open the src/server.py file, you’ll see the complete server implementation. It follows the MCP server standard, with the only difference being our use of Blaxel transport that leverages WebSockets for efficient platform serving.The main component you’ll need to modify is the tool definition:

server.py


from blaxel.core import env
from blaxel.core.mcp.server import FastMCP

from typing import Annotated
from logging import getLogger

mcp = FastMCP("mcp-helloworld-python")
logger = getLogger(__name__)

@mcp.tool()
def hello_world(
    first_name: Annotated[
        str,
        "First name of the user",
    ],
) -> str:
    """Say hello to the user"""
    return f"Hello {first_name}!"

if not env["BL_DEBUG"]:
    mcp.run(transport="ws")

Deploy your MCP server

Just run bl deploy in the folder of your project, as explained in this guide.

bl deploy

You can configure the server deployment (e.g. specify the MCP server name, etc.) in the blaxel.toml file at the root of your directory. Read the file structure section down below for more details.

Deploy your MCP server

Read our complete guide for deploying your custom MCP server on Blaxel.

Deploy with a Dockerfile

While Blaxel uses predefined, optimized container images to build and deploy your code, you can also deploy your agent using your own Dockerfile.

Deploy using Dockerfile

Deploy resources using a custom Dockerfile.

Template directory reference

blaxel.toml

This file is used to configure the deployment of the MCP server on Blaxel. The only mandatory parameter is the type so Blaxel knows which kind of entity to deploy. Others are not mandatory but allow you to customize the deployment.

name = "my-mcp-server"
workspace = "my-workspace"
type = "function"

[env]
DEFAULT_CITY = "San Francisco"

name, workspace, and type fields are optional and serve as default values. Any bl command run in the folder will use these defaults rather than prompting you for input.
[env] section defines environment variables that the MCP server can access via the SDK. Note that these are NOT secrets.

Define entrypoints in Python

Additionally, when developing in Python, you can define an [entrypoint] section to specify how Blaxel is going to start your server.

...

[entrypoint]
prod = ".venv/bin/python3 src/server.py"
dev = "npx nodemon --exec uv run python src/server.py"

...

prod: this is the command that will be used to serve your MCP server

.venv/bin/python3 src/server.py

dev: same as prod in dev mode, it will be used with the command --hotreload. Example:

npx nodemon --exec uv run python src/server.py

This entrypoint section is optional. If not specified, Blaxel will automatically detect in the MCP server’s content and configure your server’s startup settings.

Define entrypoints in TypeScript

Connect to your MCP server

Read our complete guide for connecting to and invoking an MCP server.

Get Started

Agents Hosting

Sandboxes

Batch Jobs 🆕

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Develop a custom MCP server

Quickstart

Develop the MCP server logic

Deploy your MCP server

Deploy your MCP server

Deploy with a Dockerfile

Deploy using Dockerfile

Template directory reference

blaxel.toml

Connect to your MCP server

Get Started

Agents Hosting

Sandboxes

Batch Jobs 🆕

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

​Quickstart

​Develop the MCP server logic

​Deploy your MCP server

Deploy your MCP server

​Deploy with a Dockerfile

Deploy using Dockerfile

​Template directory reference

​blaxel.toml

Connect to your MCP server

Quickstart

Develop the MCP server logic

Deploy your MCP server

Deploy with a Dockerfile

Template directory reference

blaxel.toml