Skip to main content
Blaxel has a purpose-built implementation for MCP transport that uses WebSockets protocol instead of Server-Sent Events (SSE) or stdio to feature cloud deployment capabilities. MCP servers deployed on Blaxel are only hosted server-side and cannot be installed locally. Only WebSockets protocol is supported.

​
MCP server endpoint

When you deploy an MCP server on Blaxel, a WebSocket endpoint is generated on Global Agentics Network to connect to the server. The server endpoint looks like this:
Connect to an MCP server

wss://run.blaxel.ai/{YOUR-WORKSPACE}/functions/{YOUR-SERVER-NAME}

​
Endpoint authentication

By default, MCP servers deployed on Blaxel aren’t public. It is necessary to authenticate all connections, via a bearer token. The evaluation of authentication/authorization for messages is managed by the Global Agentics Network based on the access given in your workspace. You can make an MCP server public, meaning it will bypass Blaxel authentication and you will have to implement your own authentication inside the server. This can be done through the blaxel.toml configuration file.
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").

​
Timeout limit

MCP server runtime has a hard limit of 15 minutes.

​
Call the MCP server

You can connect to your MCP server and send requests in several ways (code samples below):
  • use the Blaxel SDK to retrieve tools: best when developing an agent, particularly when running on Blaxel
  • connect from your code directly: suitable for custom implementations requiring server connection to list and call tools
  • connect from the Blaxel Console’s Playground: best for testing and validating server functionality

​
Use Blaxel SDK to retrieve tools

The following code example demonstrates how to use the Blaxel SDK to retrieve and pass an MCP server’s tools when building an agent. 

// Import tool adapter (in whichever framework format):
import { blTools } from "@blaxel/langchain";
// or
import { blTools } from "@blaxel/llamaindex";
// or
import { blTools } from "@blaxel/mastra";
// or
import { blTools } from "@blaxel/vercel";

// or

// …

const tools = blTools(['blaxel-search'])

​
Directly connect from your code

Below are snippets of code to connect to an MCP server that is deployed on Blaxel. You will need the following information:
  • BL_API_KEY: an API key to connect to your Blaxel workspace
  • BL_WORKSPACE: the slug ID for your workspace
  • MCP_SERVER_NAME: the slug name for your MCP server

import { Client as ModelContextProtocolClient } from "@modelcontextprotocol/sdk/client/index.js";
import dotenv from 'dotenv';
import { BlaxelMcpClientTransport, env } from “@blaxel/core”

// Load environment variables from .env file
dotenv.config();

async function sampleMcpBlaxel(name: string): Promise<void> {
  const apiKey = env.BL_API_KEY;
  const workspace = env.BL_WORKSPACE;

  if (!apiKey || !workspace) {
    throw new Error("BL_API_KEY and BL_WORKSPACE environment variables must be set");
  }

  const headers = {
    "X-Blaxel-Authorization": `Bearer ${apiKey}`
  };

  const transport = new BlaxelMcpClientTransport(
    `

wss://run.blaxel.ai/${workspace}/functions/${name}

`,
    headers
  );

  const client = new ModelContextProtocolClient(
    {
      name: name,
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    }
  );
  try {
    await client.connect(transport);
    const response = await client.listTools();
    console.log(`Tools retrieved, number of tools: ${response.tools.length}`);

    // Call the tool, specify the correct tool name and arguments
    const result = await client.callTool({
      name: "search_issues",
      arguments: { query: "test" }
    });
    console.log(`Tool call result: ${JSON.stringify(result)}`);
  } finally {
    await client.close();
    await transport.close();
  }
}

// Example usage
if (require.main === module) {
  sampleMcpBlaxel("MCP_SERVER_NAME").catch(console.error);
}
Requirements are as follows: 

"dependencies": {"@blaxel/core": …}

​
Connect to pre-built servers

Blaxel’s pre-built MCP servers offer two methods:
  • tools/list : method that lists the available tools and their schemas, allowing consumers (you or agents) to discover the function’s capabilities.
  • tools/call : method that lets consumers execute individual tools. It requires params with two keys:
    • name: the name of the tool to run, obtained from the listing endpoint above
    • arguments: an object with the key and values of input parameters for the execution, obtained from the listing endpoint above
Example of tools/list outbound message on a Brave Search toolkit (make sure to fill in the authentication token). 
{
	"method":"tools/list",
	"jsonrpc":"2.0",
	"id":1
}
This one returns two tools in the function: brave_web_search and brave_local_search. 
{
    "result": {
        "tools": [
            {
                "name": "blaxel_web_search",
                "description": "Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports pagination, content filtering, and freshness controls. Maximum 20 results per request, with offset for pagination. ",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "query": {
                            "type": "string"
                        },
                        "count": {
                            "type": "number"
                        },
                        "offset": {
                            "type": "number"
                        }
                    },
                    "additionalProperties": false,
                    "$schema": "http://json-schema.org/draft-07/schema#"
                }
            },
            {
                "name": "blaxel_local_search",
                "description": "Searches for local businesses and places using Brave's Local Search API. Best for queries related to physical locations, businesses, restaurants, services, etc. Returns detailed information including:\n- Business names and addresses\n- Ratings and review counts\n- Phone numbers and opening hours\nUse this when the query implies 'near me' or mentions specific locations. Automatically falls back to web search if no local results are found.",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "query": {
                            "type": "string"
                        },
                        "count": {
                            "type": "number"
                        }
                    },
                    "additionalProperties": false,
                    "$schema": "http://json-schema.org/draft-07/schema#"
                }
            }
        ]
    },
    "jsonrpc": "2.0",
    "id": "1"
}
Example of tools/call outbound message on the brave_web_search tool. 
{
	"jsonrpc":"2.0",
	"id":2,
	"method":"tools/call",
	"params":{
		"name":"blaxel_web_search",
		"arguments":{
			"query":"What is the current weather in NYC?",
			"count":1,
			"offset":1
			}
		}
}

​
Via Blaxel console

Requests to an MCP server can be made from the Blaxel console from the server deployment’s Playground page. image.png
⌘I