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.