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 HTTP Streamable, 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

Install in the default pip location

pip install math-ai-agent

Alternatively, install in the Python user directory

pip --no-cache-dir install -U --user math-ai-agent

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

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

Uninstall

Uninstall as follows:

pip uninstall math-ai-agent
pip cache purge

Configuration

`calculator-mcp` Running Locally

Copy the file config_local.yaml to ${HOME}/cfg/math-ai-agent/config_local.yaml
Set MATHAIAGENT_CONFIG for calculator-mcp running locally

export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"

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 file config_remote.yaml to ${HOME}/cfg/math-ai-agent/config_remote.yaml
Set MATHAIAGENT_CONFIG for calculator-mcp running remotely

export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"

Overriding the `calculator-mcp` URL

A non-empty CALCULATOR_MCP_URL overrides server.calculator_mcp.url.

Usage

Simply run

math-ai-agent

Health check

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

To stop, go to the running terminal and press Ctrl+C

License

The project is licensed under the MIT License.

Links

Author: Rubens Gomes

Metadata

Release files for math-ai-agent 0.0.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for math-ai-agent 0.0.16
File	Size	Uploaded
math_ai_agent-0.0.16.tar.gz	25.6 kB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for math-ai-agent 0.0.16
File	Interpreter	ABI	Platform	Reset
math_ai_agent-0.0.16-py3-none-any.whl 37.0 kB Oct 2, 2026	Python 3	none	any	Details

Total release size: 62.6 kB

Release files / math_ai_agent-0.0.16.tar.gz

Download URL	math_ai_agent-0.0.16.tar.gz
Size	25.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ca1b4481aa913d6d590da77aaa7e8b8a918f30dce5c5bd83319d481dbc4991d`
BLAKE2b-256 checksum How to use checksums	`96d2d653be992580832ca7cc1c4eef70cbc7f8d1a973b658e897ce23048941c2`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.3 CPython/3.14.7 Linux/6.17.0-1022-azure`

Release files / math_ai_agent-0.0.16-py3-none-any.whl

Download URL	math_ai_agent-0.0.16-py3-none-any.whl
Size	37.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ef683a4815878c3d46637630ffeab480cdd104b1e5d938920768edb47ddf6ede`
BLAKE2b-256 checksum How to use checksums	`8d85f68fa612f090d87785c65466cb958708060984ee2abe98926a655437dfcf`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.3 CPython/3.14.7 Linux/6.17.0-1022-azure`