Skip to main content
Glama
ThePrakashV

MCP Tool-Calling Agent

by ThePrakashV
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MCP Tool-Calling Agent

A production-ready Model Context Protocol (MCP) agent that connects a local LLM (Ollama) to multiple tool-serving backends — files, GitHub, SQL, and Python execution — with authentication, observability, security hardening, and container/orchestration deployment built in from the ground up.

Built as a hands-on learning project covering the full lifecycle of an AI agent system: from a single MCP server to a Kubernetes-deployed, Redis-backed, horizontally-scalable multi-agent architecture.

Architecture

                        ┌─────────────────────────────┐
                        │      User Request            │
                        └──────────────┬───────────────┘
                                       │
                        ┌──────────────▼───────────────┐
                        │   Agent Core (agent_core.py)  │
                        │  ┌─────────────────────────┐  │
                        │  │ 1. Authenticate (API key) │  │
                        │  │ 2. Rate limit (Redis)     │  │
                        │  │ 3. Connect to MCP servers │  │
                        │  │ 4. Ask LLM which tool(s)  │  │
                        │  │ 5. Authorize per tool     │  │
                        │  │ 6. Execute (parallel,     │  │
                        │  │    retry, timeout)        │  │
                        │  │ 7. Return final answer     │  │
                        │  └─────────────────────────┘  │
                        └───┬────────┬────────┬────────┬─┘
                            │        │        │        │
                     ┌──────▼──┐ ┌───▼────┐ ┌─▼──────┐ ┌▼────────┐
                     │  File   │ │ GitHub │ │  SQL   │ │ Python  │
                     │  MCP    │ │  MCP   │ │  MCP   │ │  Exec   │
                     │ Server  │ │ Server │ │ Server │ │ MCP     │
                     └─────────┘ └────────┘ └────────┘ └─────────┘
                            │
                     ┌──────▼──────┐        ┌─────────────┐
                     │ Ollama (LLM) │        │ Redis (rate  │
                     │  (host)      │        │ limit state) │
                     └──────────────┘        └─────────────┘

The agent connects to each MCP server as a subprocess over stdio, discovers their tools dynamically, and lets the LLM decide which tool(s) to call based on the user's request. Tool execution, authorization, retries, and metrics are all handled centrally in the agent core.

Related MCP server: Enterprise MCP Gateway and Tool Registry

Features

  • MCP Client + Multi-Server support — dynamic tool discovery across 4 independent MCP servers

  • LLM Tool-Calling — local LLM (Ollama) decides which tool to call and with what parameters

  • Parallel execution — independent tool calls run concurrently via asyncio.gather

  • Retry + timeout — exponential backoff retries and strict timeouts on all network/tool calls

  • Authentication & Authorization — API-key based auth with role-based tool permissions (admin/developer/viewer)

  • Secret management — centralized .env-backed secrets abstraction, swappable for a cloud secret manager

  • Structured logging — JSON logs with automatic request-ID tracking (contextvars)

  • Metrics — Prometheus-compatible counters and histograms (tool calls, latencies, auth failures)

  • Security hardening — subprocess-isolated Python execution, SQL injection prevention, path traversal protection, rate limiting

  • Automated tests — 17 pytest unit + integration tests covering auth, rate limiting, retries, and the full MCP pipeline

  • Containerized — Dockerfile + docker-compose (agent + Redis)

  • Kubernetes-ready — Deployment, Service, ConfigMap, Secret manifests with health probes, tested on Minikube

  • Distributed rate limiting — Redis-backed sliding-window limiter for correct behavior across multiple replicas

Tech Stack

Category

Technologies

Language

Python 3.11

Protocol

Model Context Protocol (MCP) — Client & Server SDK

LLM

Ollama (local, tool-calling capable models — e.g. qwen2.5)

Web/API

FastAPI, httpx (async)

Tools

SQLite, GitHub REST API, subprocess-isolated Python exec

Auth

API-key based, role-based authorization

Observability

python-json-logger, Prometheus client, OpenTelemetry (SDK installed)

Testing

pytest, pytest-asyncio

Containers

Docker, Docker Compose

Orchestration

Kubernetes (Minikube for local dev)

Scaling

Redis (distributed rate limiting)

Project Structure

mcp-tool-calling-agent/
├── agent/
│   └── agent_core.py          # Main agent loop: auth, LLM calls, tool routing, parallel execution
├── servers/
│   ├── file_server.py         # File read tool (path-traversal protected)
│   ├── github_server.py       # GitHub repo info + issue creation
│   ├── sql_server.py          # SQLite read-only queries (injection-hardened)
│   └── python_server.py       # Sandboxed Python code execution
├── client/
│   └── mcp_client.py          # Standalone MCP client (tool discovery demo)
├── auth/
│   ├── auth_manager.py        # Authentication + role-based authorization
│   ├── secret_manager.py      # Centralized secrets access
│   ├── rate_limiter.py        # In-memory rate limiter (single-instance)
│   └── redis_rate_limiter.py  # Redis-backed rate limiter (multi-replica)
├── observability/
│   ├── logger.py              # Structured JSON logging with request IDs
│   └── metrics.py             # Prometheus metrics definitions
├── tools/
│   └── retry_utils.py         # Retry (exponential backoff) + timeout decorators
├── tests/                     # pytest unit + integration tests
├── k8s/                       # Kubernetes manifests (Deployment, Service, ConfigMap)
├── docs/                      # Phase-by-phase build documentation
├── data/                      # SQLite database (gitignored, auto-created)
├── Dockerfile
├── docker-compose.yml
├── requirements.txt           # Local (Windows) development dependencies
├── requirements-docker.txt    # Linux-container-safe dependencies
├── pytest.ini
└── .env                       # Secrets (gitignored, never committed)

Setup Instructions

Prerequisites

  • Python 3.10+

  • Ollama installed, with a tool-calling-capable model pulled (e.g. ollama pull qwen2.5)

  • Docker Desktop (for containerized/Kubernetes runs)

  • Node.js (for MCP Inspector, optional debugging tool)

Local Development

# Clone and enter the project
git clone https://github.com/<your-username>/mcp-tool-calling-agent.git
cd mcp-tool-calling-agent

# Create and activate a virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure secrets
copy .env.example .env       # then fill in your values
# Required: AGENT_API_KEYS=devkey123:developer,adminkey456:admin,viewkey789:viewer
# Optional: GITHUB_TOKEN=... (for GitHub tools)

# Ensure Ollama is running with a tool-capable model
ollama list

# Run the agent
python -m agent.agent_core

Run Tests

pytest -v

Run with Docker Compose (agent + Redis)

docker compose build
docker compose up

Deploy to Kubernetes (Minikube)

minikube start --driver=docker
kubectl create secret generic agent-secrets --from-env-file=.env
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

minikube image build -t mcp-tool-calling-agent-agent:latest -f Dockerfile .
kubectl delete pod -l app=mcp-agent   # trigger a fresh pull of the newly built image

kubectl get pods
kubectl logs -f deployment/mcp-agent-deployment

Phase-by-Phase Build Summary

This project was built incrementally across 14 phases, each documented in detail under docs/.

Phase

Focus

Key Deliverable

1

Project Setup + MCP Basics

Environment, dependencies, MCP protocol concepts

2

First MCP Server

Single-tool file_server.py, tested via MCP Inspector

3

MCP Client + Tool Discovery

Dynamic tool discovery, no hardcoding

4

LLM Tool-Calling Agent Core

Full Think → Act → Observe → Respond loop (Ollama)

5

More Tools + Multi-Server

GitHub, SQL, Python servers; multi-server routing agent

6

Async/Parallel + Retry/Timeout

Concurrent tool execution, exponential backoff retries

7

Auth + Secret Manager

API-key auth, role-based tool authorization

8

Logging & Monitoring

Structured JSON logs, Prometheus metrics

9

Security Hardening

Sandboxed Python exec, SQL injection & path traversal defenses

10

Testing

17 pytest unit + integration tests

11

Dockerize

Dockerfile, docker-compose, Linux-compatible dependencies

12

Kubernetes Deployment

Minikube deployment with health probes, Secrets, ConfigMaps

13

Advanced Scaling

Redis-backed distributed rate limiting

14

GitHub Push + Docs

This README, repo setup, final polish

Each phase document in docs/ includes: what was built, errors encountered and how they were resolved, final working code/commands, and important notes for future reference.

Security Notes

  • All secrets live in .env, which is git-ignored and never committed.

  • The Python execution tool runs in an isolated subprocess with a strict timeout and restricted builtins (no file/network access).

  • SQL queries are restricted to SELECT only, with a dangerous-keyword blocklist and a database-level PRAGMA query_only enforcement.

  • File access is restricted to the project directory (path traversal protected).

  • Rate limiting (Redis-backed) protects against request flooding, with a fail-open policy if Redis is temporarily unavailable.

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers