Math AI Agent

A prompt chat webapp that drives an LLM call inside an agentic loop using the calculator_mcp MCP server for arithmetic operations. The key constraint is that the LLM is given explicit system instructions to use calculator_mcp for any arithmetic operations.

Features

• FastAPI web UI — simple form-based interface for submitting prompts
• MCP client — connects to a remote calculator MCP server with optional OAuth authentication
• Configurable — MCP server URL, OAuth settings, LLM endpoint and model, and logging are all driven by config.yaml
• Plain-text answers — the model is instructed to reply without LaTeX or Markdown, since the web UI renders answers in a plain <textarea>

Unsupported Features

• Server-sent events (SSE) are not supported for either LLM or MCP communication.
• Streaming communication channels, such as Streamable HTTP, are not supported. In other words, both the LLM model and the MCP server are expected to generate the entire output before sending it.
• Stateful Responses API communication may not be supported, depending on the LLM model selected in the configuration.
• Input types such as images and videos are not supported. Only text input is supported.
• Tools available to the LLM are limited to calculator_mcp. Other tool types, such as built-in tools (for example, web search and file search) and function calls, are not supported.

Bear in mind that support for the features listed above also depends on the capabilities of the selected LLM model. For example, the default configured model, NVIDIA Nemotron 3 Super, does not support storing conversation history and supports only text input.

AI Disclaimer

This project includes code and documentation created with the assistance of AI tools. For details on usage, limits, and review practices, please see the AI Disclaimer.

Prerequisites

• Python 3.14+
• pip

Installation

1. Install using pip

pip install math-ai-agent

2. Confirm the installed version matches the latest GitHub release at math-ai-agent/releases

math-ai-agent --version
pip show math-ai-agent

Uninstall

pip uninstall math-ai-agent
pip cache purge

Configuration

Settings are read from the packaged src/math_ai_agent/config.yaml.

calculator-mcp Running Locally

• Launch calculator-mcp locally following the instructions at calculator-mcp

calculator-mcp Running Remotely

Note: This requires OAuth authentication using a GitHub account. Currently, only the project author is authorized.

• Copy the settings in config_remote.yaml into src/math_ai_agent/config.yaml

Usage

1. Simply run

math-ai-agent

2. Health check

curl -v http://localhost:9090/health
# Expect: OK

3. To stop, go to the running terminal and press Ctrl+C. If Ctrl+C does not work you can try the following:

PID="$(pgrep -f math-ai-agent)"
kill -15 "${PID}"

Open Source Project Information

This project is open source and publicly hosted on GitHub at rubensgomes-org. It is published under an OSI-approved open-source license.

License

The project is licensed under the MIT License.

Links

• GitHub Project
• Agent, LLM, MCP Diagram
• Class Diagram
• Development Setup
• Docker
• LangChain Notes
• LLM Models
• LLM Tool Calls and the MCP Server
• MCP Client Sequence Diagram
• OAuth Authentication Diagram
• Ollama LLM Models
• PyCharm
• Python Coroutines
• Python Execution
• Release Process
• Tests

Author: Rubens Gomes