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 the 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>

Non-Supported 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 the Calculator MCP only. 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 configurable 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.

Installation

Prerequisites

• UNIX OS (e.g., macOS, Linux)
• curl 8.7+
• pip 26.2+
• poetry 2.4+
• python 3.14+

PyPI Package Installation

IMPORTANT: release versioning was recently reset to start again at version 0.0.1. Uninstall any previously installed version first.

1. Uninstall any previously installed release

pip uninstall math-ai-agent
# purging the cache is recommended as well
pip cache purge

2. Install into the user's home environment

# install "math-ai-agent" and dependencies into user local pip environment
# NOTE: use --no-cache-dir to avoid issues with an earlier cached version
pip --no-cache-dir install -U --user math-ai-agent --verbose

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

# show the installed version
pip show math-ai-agent

Git Clone Installation

1. git clone and install local project package using poetry

# use local `dev` folder to install the project
mkdir -p ~/dev || exit; cd ~/dev
git clone https://github.com/rubensgomes-org/math-ai-agent.git
# change to project git local directory
cd math-ai-agent
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
poetry install

Usage

Configuration

The server ships with a default config.yaml bundled inside the PyPI package. To override it, set the MATHAIAGENT_CONFIG environment variable to the absolute path of your custom configuration file:

# assuming config_local.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"

Running Using PyPI Package

NOTE: requires prior installation using pip install -U --user math-ai-agent.

1. Make a copy of config_local.yaml to a local home directory (e.g., ${HOME}/cfg/math-ai-agent/config_local.yaml).

2. Launch the PyPI-installed math-ai-agent package:

# config_local.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
# using installed package from PyPI:
math-ai-agent

3. Health check

# port is set by web.port in config_local.yaml
curl -v http://localhost:9090/health
# Expect: OK

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

Running Using Git Cloned Project - MCP Server Running Locally

NOTE: requires the calculator_mcp running locally as per instructions at calculator-mcp

1. Make a copy of config_local.yaml to a local home directory (e.g., ${HOME}/cfg/math-ai-agent/config_local.yaml).

2. Launch math-ai-agent from the local Git repo folder

# On my machine the project is installed here:
pushd ~/github/rubens/dev/python/math-ai-agent/
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
# config_local.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_local.yaml"
# ensure below port does not conflict with locally running MCP server.
poetry run math-ai-agent

3. Health check

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

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

Calculator MCP Server Running Remotely - OAuth Authentication

NOTE: requires OAuth authentication which currently only Rubens is able to authorize using his personal GitHub account.

1. Make a copy of config_remote.yaml to a local home directory (e.g., ${HOME}/cfg/math-ai-agent/config_remote.yaml).

2. Launch math-ai-agent from the local Git repo folder

# On my machine the project is installed here:
pushd ~/github/rubens/dev/python/math-ai-agent/
# ensure we are at the project git local root folder
cd $(git rev-parse --show-toplevel) || exit
# config_remote.yaml placed in my home folder
export MATHAIAGENT_CONFIG="${HOME}/cfg/math-ai-agent/config_remote.yaml"
# clean up previously created OAuth tokens
rm -fr ~/.calc-mcp-token
poetry run math-ai-agent

3. Health check

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

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

License

The project is licensed under MIT License.

Author: Rubens Gomes