Toy MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Toy MCP Server roll a d20 for my character's attack"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Toy MCP server implemented with the official MCP Python SDK.
Overview
This project implements a toy Model Context Protocol (MCP) server using Anthropic's official Python SDK mcp (PyPI, docs.claude.com).
It exposes two tools:
random_animal: returns a random animal from a predefined list of 10 animals.
roll_d20: returns a random integer simulating a roll of a 20-sided die (1–20).
The server is:
MCP-native – built using
FastMCPfrom the official SDK, implementing tools according to the MCP spec (docs.claude.com).Stateless and simple – suitable as a toy reference server.
Flexible on transport – can be run over stdio, streamable HTTP, or SSE using the
mcpCLI.
Related MCP server: Echo MCP Server
Installation
From the project root:
uv syncIf you are not using uv, you can install dependencies with:
pip install -e .This will install the mcp[cli] SDK, which provides the MCP runtime and developer tooling.
You should also have Claude Desktop installed if you want to register this server as a Claude MCP connector, as described in the MCP docs (docs.claude.com).
Running the MCP server
The recommended way to run this server is via the mcp CLI, which understands MCP transports and discovers the FastMCP instance defined in main.py.
Dev mode (MCP Inspector / stdio)
From the project root:
uv run mcp dev main.pyThis runs the server in development mode (stdio transport) and opens the MCP Inspector, where you can:
Inspect the server’s declared tools.
Manually invoke
random_animalandroll_d20.
Under the hood:
uv runensures themcpCLI runs inside this project’s environment (with the rightmcpversion from PyPI).mcp dev main.pystarts your server as a subprocess over stdio and connects an MCP Inspector client to it.
Direct execution
You can also run the server directly (for example, to integrate with a custom MCP client over stdio or another supported transport):
python main.pyThis calls mcp.run() on the FastMCP instance defined in main.py, starting an MCP server loop using the SDK’s defaults.
This is useful for:
Custom MCP clients that you write yourself.
Simple testing of the server process and logging without the inspector.
Note that direct execution does not automatically register the server with Claude Desktop; it just runs the MCP server.
Registering the server with Claude Desktop
Once Claude Desktop is installed, you can register this MCP server so Claude can discover and launch it automatically.
From the project root, run:
uv run mcp install main.pyWhat this does conceptually:
Inspects
main.pyto find theFastMCPserver.Prompts you (if needed) for details like the server name and command.
Writes a small manifest/config entry into Claude Desktop’s MCP configuration directory (a per-user config location), telling Claude:
“This server exists and is named e.g.
Toy MCP Server.”“To start it, run:
python <path-to-your-project>/main.py(with the proper environment).”
Importantly:
Your code is not copied or reinstalled; it stays in your project folder.
The “install” step only creates metadata so Claude Desktop knows how to launch the existing script as an MCP server.
After running mcp install:
Restart Claude Desktop (if it was open).
Open its settings/preferences and navigate to the MCP / Tools / Servers section.
You should see this server listed (with the name you chose); enable it if needed.
Claude will now spawn the server process on demand and call the tools (
random_animal,roll_d20) via MCP.
Example tool usage (conceptual)
The MCP client (e.g. Claude Desktop, MCP Inspector, or a custom MCP client) will discover and call tools using the MCP protocol rather than raw HTTP endpoints.
List tools – the client inspects the server’s declared tools (
random_animal,roll_d20) via MCP’s capabilities and tool metadata, similar to the examples in the MCP docs (docs.claude.com).Call
random_animal– the client sends an MCP tool invocation with no arguments and receives a string result like"tiger".Call
roll_d20– the client sends an MCP tool invocation with no arguments and receives an integer result between 1 and 20.
Integrating with a local LLM (e.g. Claude Desktop, LM Studio)
Because this server is MCP-native, the ideal integration path is with MCP-aware clients (e.g. Claude Desktop, Claude Code, MCP Inspector) that speak the protocol directly as described in the MCP docs (docs.claude.com).
For LM Studio or other local LLM runtimes that don’t yet natively support MCP, you can:
Run this MCP server (via stdio or HTTP/SSE using the SDK’s transports).
Write a thin adapter that acts as:
An MCP client on one side (talking to this server via the
mcpPython SDK).A tool/callout provider on the other side (using whatever HTTP or plugin mechanism LM Studio exposes; see e.g. this overview of LM Studio).
That way you keep this project focused purely on the MCP server, while still being able to integrate it into your local LLM workflow.
License
GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007
Available Tools
2 toolsrandom_animalA
Select a random animal from a predefined list of 10 animals.
Returns the animal name as a string.
Inputs: no named parameters. Returns: result
roll_d20A
Roll a 20-sided dice.
Returns an integer between 1 and 20 (inclusive).
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools operate on completely unrelated concepts: picking an animal versus rolling a die. There is no plausible way an agent would confuse them, and each description states its return type explicitly.
Both names are snake_case and lowercase, which is consistent. However, 'roll_d20' follows a verb_noun pattern while 'random_animal' is adjective_noun, a minor deviation from a single predictable convention.
Two tools is at the thin end for a general-purpose 'toy' server; each tool earns its place but the surface feels minimal. It sits in the borderline band of 1-2 tools for the apparent scope.
The implied domain is lightweight random generators, and obvious companions are absent: no coin flip, generic random number, other dice sizes, or list/parameter options. The two tools work as-is but leave an agent without common adjacent operations.
Maintenance
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA demonstration MCP server that provides basic utility tools including hello world functionality and string reversal operations. Shows how to build and deploy MCP tools using the MCPO orchestrator framework.GPL 3.0
- FlicenseNot gradedqualityDmaintenanceA simple demonstration MCP server that provides an echo tool and resource for learning how to build MCP servers. Serves as a starting point and template for creating custom MCP server implementations.1-
- FlicenseBqualityDmaintenanceA simple demonstration MCP server that provides basic utility tools including dice rolling and number addition functionality. This server serves as a tutorial example for setting up both local and remote MCP servers using FastMCP.3-
- FlicenseNot gradedqualityDmaintenanceA simple MCP server built with MCPize providing hello and echo tools for demonstration purposes.-