Skip to main content

Develop the First MCP Server

Recommend using Node.js 18 or above

This article will step-by-step explain how to develop an MCP Server on the CloudBase platform, including the following steps:

  1. Create an MCP Server cloud hosting service using a template.
  2. Develop the MCP Server using the CloudBase MCP framework
  3. Debug the MCP Server locally using the graphical interface
  4. Deploy to production, overwriting the existing cloud hosting service
  5. Use the MCP Server in the Agent

Create a Blank MCP Server​

Go to the CloudBase Platform to create a blank MCP Server, setting its identifier as first-mcp.

This step will automatically create a Cloud Hosting service to host the MCP Server. Later in this article, we will develop our own MCP Server and overwrite this Cloud Hosting service.

Prepare the code​

We provide a basic MCP Server template, which includes a complete MCP Server project. You can modify it based on this project to develop your own MCP Server.

This article will introduce how to use this project code for local development, debugging, and deployment.

Click here to download the project code

Install Dependencies​

Download the project code, unzip it, enter the project directory, and execute the following command in the command line to install dependencies:

npm i

Add the First Tool to the MCP Server​

Modify the implementation in src/server.ts to create a tool that retrieves user access information, which returns the latest count records of user access.

You can also use the tools provided by the template to proceed directly to the next step.

import { ContextInjected, TcbExtendedContext } from '@cloudbase/functions-typings';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import tcb from '@cloudbase/node-sdk';
import { z } from 'zod';

export function createServer(context: ContextInjected<TcbExtendedContext>) {
  const server = new McpServer(
    {
      name: 'Basic Server',
      version: '1.0.0',
    },
    { capabilities: { tools: {} } },
  );

  const env = context.extendedContext?.envId || process.env.CLOUDBASE_ENVIRONMENT; // Read from environment variables during local development
  const secretId = context.extendedContext?.tmpSecret?.secretId;
  const secretKey = context.extendedContext?.tmpSecret?.secretKey;
  const sessionToken = context.extendedContext?.tmpSecret?.token;

  // Create a Cloudbase Node sdk instance
  const app = tcb.init({
    env,
    secretId,
    secretKey,
    sessionToken,
  });

  server.registerTool(
    'getUserVisitInfo',
    {
      description: 'Retrieve the latest user access information',
      // Tool input parameters
      inputSchema: {
        count: z.number().describe('Retrieve the latest {count} user access records'),
      },
      // Tool output parameters
      outputSchema: {
        total: z.number().describe('Total number of user access records in the data model'),
      },
    },
    async ({ count }) => {
      const res = await app.models.sys_user_dau.list({
        pageSize: count,
        getCount: true,
        orderBy: [
          {
            visit_time: 'desc',
          },
        ],
      });

      const structuredContent = {
        total: res.data.total,
        records: res.data.records.map((x) => ({
          device: x.device,
          visitTime: x.visit_time,
        })),
      };

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(structuredContent),
          },
        ],
        structuredContent,
      };
    },
  );

  // todo
  // You can add more tools

  return { server };
}

Local Debugging of MCP Server​

Add Environment Variables File​

Create a .env.development file and fill in the following content:

SKIP_VERIFY_ACCESS=true

The file defines the environment variables:

  • SKIP_VERIFY_ACCESS=true: Setting this will skip token verification. The original token verification will only allow calls from tokens with API Key and super administrator identities.
tip

Setting the SKIP_VERIFY_ACCESS environment variable facilitates local debugging, but it is not recommended to configure it in the online production environment.

Start the Local MCP Server​

npm run login # Log in to CloudBase
npm run dev

Once started, the service will be available at http://localhost:3000/messages.

Modifying the code will trigger recompilation and restart the service.

Start Graphical Interface Debugging​

Open another terminal and start @modelcontextprotocol/inspector:

npx -y @modelcontextprotocol/inspector

Based on the terminal output, access the debugging address to view the debugging page.

  1. On the left, select the Streamable HTTP type and fill in the URL as http://localhost:3000/messages
  2. Click Connect on the left
  3. Under the Tools tab, click List Tools to display the tool list
  4. Select any tool to invoke

Build​

After completing development and debugging, run the build command in the project root directory:

npm run build

Deploy​

After the build is completed, run the deployment command:

npm run login
npm run deploy

After selecting the environment, enter the service name specified when creating the MCP service earlier, for example, first-mcp.

Use the Online MCP Server​

After deployment, you can read the following documentation to use the MCP Server:

Troubleshooting​

MCP Server cannot connect during local debugging​

Check whether the local environment variables are set correctly and whether the local port is occupied.

You can press F12 in the inspector interface to open the browser's debugging tools and view network requests.

Check the response returned by a request similar to http://localhost:6277/mcp?url=https%3A%2F%2Flowcode-2gp2855c5ce22e35.api.tcloudbasegateway.com%2Fv1%2Fcloudrun%2Fmcp-kuaidi100-qt03oc%2Fmessages&transportType=streamable-http. Usually, if the connection fails, corresponding error messages will be displayed here.