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 MCP server and a web application to query it (MCP Inspector, managed by MCP) locally.


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

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

Template directory reference

blaxel.toml

The MCP server deployment can be configured via the blaxel.toml file in your MCP server directory. 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"

[[triggers]]
  id = "trigger-my-mcp"
  type = "http"
[triggers.configuration]
  path = "functions/my-mcp" # This will create this endpoint on the following base URL: https://run.blaxel.ai/{YOUR-WORKSPACE}/
  authenticationType = "public"

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.
[[triggers]] and [triggers.configuration] sections defines ways to send requests to the MCP servers. You can also make them either private (default) or public (authenticationType = "public").

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

Deploy your MCP server

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

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

Template directory reference

blaxel.toml

Deploy 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

​Template directory reference

​blaxel.toml

Deploy your MCP server

Quickstart

Develop the MCP server logic

Template directory reference

blaxel.toml