> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Adapt an existing MCP server for Blaxel

> Step-by-step guide to convert an existing stdio-based MCP server to streamable HTTP transport so you can deploy and host it on Blaxel.

MCP ([Model Context Protocol](https://github.com/modelcontextprotocol)) servers provide tools (individual capabilities for accessing specific APIs or databases) that can be used by AI agents. These servers can be hosted on Blaxel's computing platform and used by AI agents via each server's global endpoint.

This quickstart walks you through the process of adapting an existing stdio-based MCP server for deployment on Blaxel using the streamable HTTP transport.

## Install the Blaxel CLI

Run the installer in a terminal:

<CodeGroup>
  ```shell macOS and Linux theme={null}
  curl -fsSL https://blaxel.ai/install.sh | sh
  ```

  ```powershell Windows theme={null}
  irm https://blaxel.ai/install.ps1 | iex
  ```
</CodeGroup>

The installer checks the Blaxel CLI (`bl`) against the release checksums, installs it, and adds it to your `PATH`. On macOS and Linux, it also installs completions for your current shell if you use zsh, bash, or fish. On Windows, [configure PowerShell completions](/cli-reference/introduction#shell-autocompletion) separately. It then runs [`bl setup`](/cli-reference/commands/bl_setup), which shows what it found and installs it when you press Enter: the [Blaxel skills](/skills-mcp#blaxel-skills) and MCP servers for the coding agents on your machine (Claude Code, Codex, Cursor and others), then the browser login. Run it again at any time to add what is missing.

<AccordionGroup>
  <Accordion title="Install with Homebrew" icon="beer-mug-empty">
    ```shell theme={null}
    brew install blaxel-ai/blaxel/blaxel
    bl setup
    ```

    Homebrew 6.0.0+ requires explicit trust for non-official taps, so use the fully qualified formula name.
  </Accordion>

  <Accordion title="Installer options" icon="sliders">
    On macOS and Linux, set these variables for `sh`:

    | Variable | Effect |
    | - | - |
    | `VERSION=v0.1.119` | Install that release instead of the latest |
    | `BINDIR=/usr/local/bin` | Install to that folder instead of `~/.local/bin` |
    | `BL_INSTALL_SETUP=false` | Install the CLI only, and run `bl setup` later |
    | `BL_INSTALL_SKILLS=false` | Leave your coding agents alone |
    | `BL_INSTALL_PATH=false` | Do not add `bl` to your `PATH` |
    | `BL_INSTALL_COMPLETION=false` | Skip the shell completions |

    For example, to install a specific release for all users:

    ```shell theme={null}
    curl -fsSL https://blaxel.ai/install.sh | sudo VERSION=v0.1.119 BINDIR=/usr/local/bin sh
    ```

    Under `sudo`, the installer still sets up your own shell, coding agents and login. In CI, it installs the CLI only and leaves the shell configuration and coding agents alone. On Windows, run `$env:BL_INSTALL_SETUP = "false"` before the installer to install the CLI only.
  </Accordion>
</AccordionGroup>

The installer logs you in. To log in again later, open a terminal and run:

```bash theme={null}
bl login
```

## Get the example project

This quickstart adapts the simple stdio-based MCP weather server from the [official Model Context Protocol GitHub repository](https://github.com/modelcontextprotocol/).

<Tabs>
  <Tab title="TypeScript">
    Clone the repository and change to the project working directory:

    ```bash theme={null}
    git clone https://github.com/modelcontextprotocol/quickstart-resources.git
    cd quickstart-resources/weather-server-typescript
    ```
  </Tab>

  <Tab title="Python">
    Clone the repository and change to the project working directory:

    ```bash theme={null}
    git clone https://github.com/modelcontextprotocol/quickstart-resources.git
    cd quickstart-resources/weather-server-python
    ```
  </Tab>
</Tabs>

## Adapt the server

<Note>
  If your MCP server is already configured to use streamable HTTP, you may skip this step.
</Note>

Blaxel uses streamable HTTP as the transport layer for MCP servers deployed on its infrastructure. If your MCP server uses stdio (as in this example), you must adapt it to use streamable HTTP instead. The host name and port for the server to bind to are automatically injected by Blaxel during deployment, as `HOST` and `PORT` environment variables.

<Tabs>
  <Tab title="TypeScript">
    <Note>
      The changes shown below are illustrative only and based on the [Blaxel MCP server template for TypeScript](https://github.com/blaxel-templates/template-mcp-ts).
    </Note>

    Add Express to handle HTTP requests and responses:

    ```bash theme={null}
    npm install express
    npm install --save-dev @types/express
    ```

    Here is an example of how you could adapt the existing `src/server.ts` file for a streamable HTTP server.

    ```tsx theme={null}
    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
    import { z } from "zod";
    import express from 'express';

    // ... code ...

    const app = express();
    app.use(express.json());

    app.post('/mcp', async (req, res) => {
      const transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: undefined,
        enableJsonResponse: true,
      });

      res.on('close', () => {
        transport.close();
      });

      await server.connect(transport);
      await transport.handleRequest(req, res, req.body);
    });

    const port = parseInt(process.env.PORT || '8000');
    const host = process.env.HOST || '::';

    app.listen(port, host, () => {
      console.log(`MCP Server running on http://${host}:${port}/mcp`);
    }).on('error', error => {
      console.error('Server error:', error);
      process.exit(1);
    });
    ```
  </Tab>

  <Tab title="Python">
    <Note>
      The changes shown below are illustrative only and based on the [Blaxel MCP server template for Python](https://github.com/blaxel-templates/template-mcp-py).
    </Note>

    Here is an example of how you could adapt the existing `weather.py` file for a streamable HTTP server.

    ```python theme={null}
    from typing import Any
    import httpx, os
    from mcp.server.fastmcp import FastMCP

    # Initialize FastMCP server
    mcp = FastMCP(
        "weather",
        stateless_http=True,
        host=os.getenv('HOST', "::"),
        port=os.getenv('PORT', "8000")
    )

    # ... code ...

    def main():
        # Initialize and run the server
        mcp.run(transport='streamable-http')

    if __name__ == "__main__":
        main()
    ```
  </Tab>
</Tabs>

## Create the deployment configuration

Blaxel looks for a `blaxel.toml` file to configure the deployment of the MCP server on Blaxel. This file is not mandatory; if the file is not found or a required option is not set, you will be prompted for the information during deployment.

Create a new `blaxel.toml` file with the following content:

```toml theme={null}
type = "function"

[runtime]
transport = "http-stream"
```

Blaxel also automatically detects a Dockerfile at the root of the project and uses it to create and deploy a container image of your MCP server. This is a very useful feature that allows you to completely customize the deployment environment for your MCP server, including installing additional system dependencies and using specific versions of libraries or tools.

Create a new `Dockerfile` with the following content:

<Tabs>
  <Tab title="TypeScript">
    ```dockerfile theme={null}
    FROM node:20-alpine

    WORKDIR /app

    RUN apk update \
        && apk add build-base curl ca-certificates

    COPY . .

    RUN npm install

    RUN npm run build

    EXPOSE 8000

    CMD [ "node", "build/index.js" ]
    ```
  </Tab>

  <Tab title="Python">
    ```dockerfile theme={null}
    FROM python:3.12-slim

    RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential curl ca-certificates \
      && rm -rf /var/lib/apt/lists/*

    RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
      && mv /root/.local/bin/uv /usr/local/bin/uv

    WORKDIR /app

    COPY . .

    RUN uv sync --frozen --no-dev

    EXPOSE 8000

    CMD ["uv", "run", "weather.py"]
    ```
  </Tab>
</Tabs>

## Deploy the MCP server on Blaxel

Deploy the server on Blaxel by running the following command:

```bash theme={null}
bl deploy
```

Blaxel will handle the build and deployment, producing an HTTPS endpoint on Global Agentics Network. The server endpoint looks like this:

```text theme={null}
https://run.blaxel.ai/{YOUR-WORKSPACE}/functions/{YOUR-SERVER-NAME}/mcp
```

You can now [connect to this endpoint from any MCP-aware client](/Functions/Invoke-functions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.