Students Architecture MCP Server

Students Architecture

Example project that implements a REST API and an MCP interface to manage students.

Author: MsC Felipe Buitrago Carmona

Affiliation: Department of Systems and Informatics, Faculty of Artificial Intelligence and Engineering, University of Caldas

Description:

• Layered architecture: presentation (REST + MCP), business (service), data (repositories), models (DTOs and entities).

• Supports JSON and SQLite persistence with dynamic selection via .env.

Requirements

• Python 3.12+ (virtual environment recommended)

• Dependencies listed in requirements.txt.

Quick Installation

1. Create and activate a virtualenv:

python -m venv venv
& venv\Scripts\Activate.ps1

2. Install dependencies:

pip install -r requirements.txt

Configuration (.env)

• Copy or create a .env file in the root with values such as:

FASTMCP_STATELESS_HTTP=true
REPO_TYPE=json      # o sqlite
JSON_PATH=students.json
SQLITE_PATH=students.db
API_PORT=5000
MCP_PORT=9000

Changing REPO_TYPE between json and sqlite selects the persistence implementation.

Note: after changing .env restart the server so the repository factory reads it.

Run REST API (development)

venv\Scripts\python.exe -m uvicorn main_api_rest_server:app --reload --port 5000

Run MCP server

venv\Scripts\python.exe main_mcp_server.py

Main routes (REST)

• GET /students — list students

• POST /students — create student

• GET /students/{id} — get student

• PUT /students/{id} — update

• DELETE /students/{id} — delete

curl example to create a student:

curl -X POST http://localhost:5000/students -H "Content-Type: application/json" -d '{"name":"Ana","email":"ana@example.com","age":21,"career":"Ingenieria","semester":4}'

Useful notes

• If you use a debugger (e.g., PyCharm) and see a TypeError related to loop_factory, the startup contains a compatibility for asyncio.run in main_api_rest_server.py.

• Pydantic shows a warning if you use orm_mode with v2; it is recommended to use from_attributes when migrating to Pydantic v2.

Claude Desktop Configuration Install Claude Desktop, then go to the bottom left, where the username appears, then the Settings section, then the Developer section, Edit Config, and paste the following JSON.

{
  "mcpServers": {
    "students_architecture": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:9000/mcp",
        "--allow-http"
      ],
      "env": {
        "MCP_TRANSPORT_STRATEGY": "http-only"
      }
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat",
    "coworkWebSearchEnabled": true,
    "ccdScheduledTasksEnabled": false
  }
}

Contact MsC Felipe Buitrago Carmona felipe.buitrago@ucaldas.edu.co Department of Systems and Informatics University of Caldas