Skip to main content
Glama

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 MCP

The dependency always points inward:

CLI / MCP / OpenAI SDK  →  application  →  domain

The 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.py

The menu allows:

  1. Talk to the OpenAI agent (uses OPENAI_API_KEY from .env).

  2. Test addition, subtraction, multiplication, and division locally, without API cost.

  3. See the tools that the MCP server publishes.

Run the MCP server

.\.venv\Scripts\python.exe .\run_mcp.py

To 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 -v

How to add a math tool

  1. Create the pure function and its docstring in src/math_assistant/domain/operations.py.

  2. Add it to MATH_OPERATIONS in src/math_assistant/application/tool_catalog.py.

  3. 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 tools
addA

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

    A3.7/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • F
      license
      A
      quality
      D
      maintenance
      A 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
      -