math-mcp-lab
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., "@math-mcp-lab Calculate 15 + 27 and multiply the result by 2"
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.
Math Lab: MCP + OpenAI Agents SDK
This project uses the same math logic from two adapters:
An MCP server for Codex, the MCP Inspector, or any compatible client.
An agent built with the OpenAI Agents SDK for natural language conversation.
Packaged as an installable Python package (pip install -e .), with src/ layout and clean layered architecture.
Structure
pyproject.toml # Metadata, dependencias y entry points del paquete
src/
└── math_assistant/
├── domain/ # Reglas matemáticas puras (sin dependencias externas)
├── application/ # Catálogo de capacidades públicas
├── infrastructure/ # Adaptadores para MCP (FastMCP) y OpenAI Agents SDK
└── presentation/ # Interfaz de terminal
tests/
├── unit/ # Prueban dominio y catálogo
└── integration/ # Comprueban que los adaptadores se construyen
run_cli.py # Entry point: interfaz amigable para aprender y probar
run_mcp.py # Entry point: STDIO exclusivo para el cliente MCPThe dependency always points inward:
CLI / MCP / OpenAI SDK → application → domainThe domain does not know FastMCP, OpenAI, an API key, or print. That's why it can be tested quickly and without a network.
Related MCP server: Explore MCP
Installation
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"Copy your OPENAI_API_KEY into a .env file at the root (it is never committed to git).
Run the friendly interface
.\.venv\Scripts\python.exe .\run_cli.pyThe menu allows:
Talk to the OpenAI agent (uses
OPENAI_API_KEYfrom.env).Test addition, subtraction, multiplication, and division locally, without API cost.
See the tools that the MCP server publishes.
Run the MCP server
.\.venv\Scripts\python.exe .\run_mcp.pyTo inspect it with MCP Inspector:
npx @modelcontextprotocol/inspector "C:\ruta\completa\a\math-mcp-lab\.venv\Scripts\python.exe" "C:\ruta\completa\a\math-mcp-lab\run_mcp.py"Use absolute paths: the Inspector does not always respect the current working directory.
Do not add print() inside run_mcp.py or the MCP adapter: the standard output channel (stdout) is reserved for the protocol's JSON-RPC messages. The friendly interface lives in run_cli.py for that reason.
Integration with Codex
.codex/config.toml (not versioned, it's local machine config) points Codex to the MCP server. If you use Codex CLI, create your own:
[mcp_servers.math]
command = "C:\\ruta\\completa\\a\\math-mcp-lab\\.venv\\Scripts\\python.exe"
args = ["C:\\ruta\\completa\\a\\math-mcp-lab\\run_mcp.py"]
cwd = "C:\\ruta\\completa\\a\\math-mcp-lab"Tests
.\.venv\Scripts\python.exe -m unittest discover -s tests -vHow to add a math tool
Create the pure function and its docstring in
src/math_assistant/domain/operations.py.Add it to
MATH_OPERATIONSinsrc/math_assistant/application/tool_catalog.py.Run the tests.
Both adapters will expose it automatically: FastMCP turns it into an MCP tool and the Agents SDK into a function tool.
Available Tools
18 toolsaddA
Add two numbers.
Inputs: a (required), b (required). Returns: result
cosineB
Calculate cosine; angles are degrees by default.
Inputs: angle (required), degrees. Returns: result
divideB
Divide the first number by the second.
Inputs: a (required), b (required). Returns: result
factorialA
Calculate the factorial of a non-negative integer.
Inputs: number (required). Returns: result
gcdB
Calculate the greatest common divisor of two integers.
Inputs: a (required), b (required). Returns: result
is_primeA
Return whether a number is prime.
Inputs: number (required). Returns: result
lcmA
Calculate the least common multiple of two integers.
Inputs: a (required), b (required). Returns: result
logarithmA
Calculate the logarithm of a positive number using the specified base.
Inputs: number (required), base. Returns: result
meanA
Calculate the arithmetic mean of a non-empty list.
Inputs: numbers (required). Returns: result
medianB
Calculate the median of a non-empty list.
Inputs: numbers (required). Returns: result
multiplyA
Multiply two numbers.
Inputs: a (required), b (required). Returns: result
nth_rootC
Calculate the nth root of a number.
Inputs: n (required), number (required). Returns: result
powerA
Raise a number to an exponent.
Inputs: base (required), exponent (required). Returns: result
sineA
Calculate sine; angles are degrees by default.
Inputs: angle (required), degrees. Returns: result
square_rootA
Calculate the square root of a non-negative number.
Inputs: number (required). Returns: result
standard_deviationA
Calculate the population standard deviation of a non-empty list.
Inputs: numbers (required). Returns: result
subtractB
Subtract the second number from the first.
Inputs: a (required), b (required). Returns: result
tangentA
Calculate tangent; angles are degrees by default.
Inputs: angle (required), degrees. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool maps to a distinct mathematical operation; even closely related functions like square_root and nth_root are clearly separated by their descriptions. There is no meaningful overlap or ambiguity among the eighteen tools.
All tool names are lowercase, multi-word names use consistent snake_case, and each name directly reflects its operation. The naming style is uniform across arithmetic, statistics, and number theory functions.
Eighteen tools is slightly above the ideal 3-15 range, but each function serves a distinct and commonly needed math purpose. The count is not bloated; it simply reflects a broad but focused math utility surface.
The set covers arithmetic, powers/roots, logarithms, basic trigonometry, descriptive statistics, and number theory well. Minor gaps like modulo, absolute value, or inverse trig exist, but agents can handle most common math tasks without dead ends.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server exposing the Backtest360 engine API as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA learning-focused MCP server that demonstrates how to build arithmetic tools for AI assistants, currently featuring addition functionality with structured input/output.112 npmMIT
- FlicenseNot gradedqualityDmaintenanceA demonstration MCP server that exposes basic arithmetic tools (add, subtract, ping) through FastAPI and shows how to integrate them with OpenAI's tool-calling API for LLM orchestration.-
- FlicenseNot gradedqualityDmaintenanceA simple demonstration MCP server built with FastMCP that exposes basic calculator operations (add, subtract, multiply, divide) as tools for MCP clients like GitHub Copilot Agent mode.-
- FlicenseAqualityDmaintenanceA basic MCP server built with the FastMCP framework that provides fundamental mathematical operations like addition, subtraction, multiplication, and division. It serves as a demonstration for integrating math-based tools into MCP-compatible environments like Cursor IDE.4-