Skip to content
Flexus Documentation

MCP Basics: Creating Your First Server

This guide will walk you through the process of creating a basic “Hello, World” MCP server, registering it in Flexus, and calling it from a bot.

The MCP Protocol

Before we start, it’s important to understand the simple protocol MCP uses for communication over standard input/output (stdio). The Flexus MCP Agent expects your server to respond to two main commands:

  1. {"command": "list_tools"}: The agent sends this to discover the functions your server provides. Your server must respond with a JSON object containing a tools array.
  2. {"command": "call_tool", "tool_name": "...", "parameters": {...}}: The agent sends this to execute a specific function. Your server should perform the action and return a result.

Step 1: Creating a Simple MCP Server

You can write an MCP server in any language. Here is an example of a very basic server written in Python. This server will provide a single tool called greet that takes a name as a parameter.

Create a file named my_mcp_server.py:

import sys
import json


def main():
    # The list of tools this server provides.
    tools = [
        {
            "name": "greet",
            "description": "Returns a personalized greeting.",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "The name of the person to greet."
                    }
                },
                "required": ["name"]
            }
        }
    ]


    for line in sys.stdin:
        try:
            request = json.loads(line)
            command = request.get("command")


            if command == "list_tools":
                response = {"tools": tools}
            elif command == "call_tool":
                tool_name = request.get("tool_name")
                params = request.get("parameters", {})


                if tool_name == "greet":
                    name = params.get("name", "World")
                    result = f"Hello, {name}!"
                    response = {"content": [{"text": result}]}
                else:
                    response = {"error": f"Tool '{tool_name}' not found."}
            else:
                response = {"error": f"Unknown command '{command}'."}


        except json.JSONDecodeError:
            response = {"error": "Invalid JSON input."}


        # Send the response back to the agent.
        sys.stdout.write(json.dumps(response) + '\\n')
        sys.stdout.flush()


if __name__ == "__main__":
    main()

This script listens for JSON requests on stdin, processes them, and writes JSON responses to stdout.

Step 2: Registering the MCP Server in Flexus

Now that you have a server script, you need to tell Flexus how to run it.

  1. Navigate to the MCP Section In the Flexus UI, go to the group where you want to add the server and find the “MCP Servers” or “Integrations” section.

  2. Add a New MCP Server Click “Add MCP Server” to open the configuration form.

    The "Add MCP Server" form in the Flexus UI

  3. Fill in the Details

    • Name: My First MCP Server
    • Description: A simple server that provides a greeting.
    • Command: python3 /path/to/your/my_mcp_server.py (Important: Use the absolute path to the script on the machine where the Flexus agent is running.)

  4. Save the Server Click “Create MCP Server”. Flexus will now be aware of your server and will launch it when needed.

Step 3: Using the MCP Server in a Bot

Once your MCP server is registered, Flexus automatically creates a CloudTool that your bots can use to interact with it. This tool acts as a proxy, handling all the communication for you.

The generated CloudTool will have a name based on the MCP server’s ID and name, for example: mcp_abc123_My_First_MCP_Server.

Here’s how you would call it from a bot’s code:

# Inside your bot's logic


# 1. Find the tool. You can list available tools to find the exact name.
# For this example, we'll assume the tool name is 'mcp_abc123_My_First_MCP_Server'.


tool_name = "mcp_abc123_My_First_MCP_Server"


# 2. Define the arguments for the tool call.
# Our MCP tool has a 'command' and 'args' structure.
arguments = {
    "command": "greet",
    "args": {
        "name": "Alice"
    }
}


# 3. Call the tool using the Flexus client kit.
# result = await flexus_client.call_tool(tool_name, arguments)


# The 'result' would contain something like:
# {"result": "Hello, Alice!"}

That’s it! You have successfully created an external MCP server and integrated it with Flexus. This simple pattern allows you to extend your bots with powerful custom capabilities.

Next, explore more complex integrations in the Advanced MCP guide.