Quaestio MCP Server

Quaestio is a Model Context Protocol (MCP) server for analyzing, solving, and verifying questions. It exposes MCP tools so that a compatible host can send questions, attachments, and study materials and receive structured, traceable, and conservative results.

The server is not a user interface or a language model. It is the MCP layer that organizes the input contract, calls the configured components, validates the responses, and returns a structured decision to the client.

What is MCP in this project

MCP is an open protocol for connecting host applications to servers that offer tools and data in a standardized way. In Quaestio:

host MCP / cliente MCP
          │
          │ transporte stdio + JSON-RPC
          ▼
Quaestio MCP Server
          │
          ├── ferramentas de resolução e verificação
          ├── parsing, OCR e PDF
          ├── materiais de estudo e busca semântica
          ├── análise e execução controlada de código
          └── políticas de confiabilidade e auditoria

The MCP Server currently exposes the tools primitive. It does not publish resources, resource templates, or prompts as separate MCP primitives. Materials, OCR, PDFs, and server capabilities are accessed through tools.

Protocol references used:

• MCP — official documentation;

• MCP 2026-07-28 specification;

• server discovery;

• tools specification;

• stdio specification;

• Official Python SDK;

• official reference servers.

Capacities

• solve multiple-choice and open-ended questions;

• process questions with inline images;

• run consensus between two configurable LLM backends;

• prepare non-English questions for the configured models;

• preserve alternatives, indexes, formulas, code, and attachments;

• structurally verify and, when configured, semantically verify a proposal;

• apply optional deterministic and symbolic mathematical verification;

• add and search local study materials;

• use semantic embeddings with TF-IDF fallback;

• extract text from images with Tesseract;

• extract and interpret text from PDFs;

• analyze code without executing it;

• compile/check syntax without executing the code;

• run Python or JavaScript only in a Docker sandbox;

• evaluate batches with an answer key and compute metrics;

• return a trace of the executed steps.

Reliability principles

The server is designed to fail explicitly when there is not enough evidence.

• absence of a backend or valid proposal results in needs_review;

• disagreement between the models is not silently resolved;

• semantic verification is not treated as deterministic proof;

• verified is reserved for reliable evidence, such as deterministic mathematical checks;

• confidence declared by a model is limited by the server;

• inputs, attachments, context, and retrieved materials are treated as untrusted data, never as system instructions;

• failures of external providers are converted into warnings and structured states;

• the server must not be used to treat an LLM answer as a guarantee of correctness.

Internal architecture

tools/call
   │
   ▼
MCP boundary
   │  valida argumentos e serializa resultado
   ▼
QuaestioService
   ├── classificação
   ├── recuperação de materiais
   ├── preparação linguística/OCR
   ├── solver determinístico ou LLM
   ├── consenso
   ├── verificação estrutural/semântica
   └── avaliação e trace

The main internal components are:

• models.py: canonical contracts and public states;

• mcp_server.py: MCP registration, dispatch, and transport;

• service.py: pipeline orchestration;

• backends.py: deterministic, LLM, translation, and consensus backends;

• verification.py: structural and mathematical validations;

• semantic_verifier.py: optional independent semantic review;

• knowledge.py and embeddings.py: local knowledge base and semantic retrieval;

• ocr.py and pdf.py: local content extraction;

• sandbox.py: controlled code execution in Docker.

Transport and MCP cycle

The main transport is stdio, suitable for local servers. The host starts the process and talks to it over stdin and stdout; each message is JSON-RPC. Startup logs are sent to stderr so as not to corrupt the MCP channel.

The server implements the modern flows:

1. server/discover — discovery of version, identity, capabilities, and instructions;

2. tools/list — deterministic discovery of the tools, schemas, and cache;

3. tools/call — execution of a tool with a structured result.

When the official mcp package is installed, the server uses the modern SDK with stdio transport. Without the package, it uses the minimal stdio implementation included in the project. Both paths register the same set of tools and follow the modern contract. Each tool declares inputSchema and outputSchema; the minimal stdio path also validates arguments before executing the handler.

The server does not start an HTTP port. Streamable HTTP remains out of scope for this version.

Installation

Requirements:

• Python 3.11 or higher;

• pip;

• credentials for an LLM endpoint compatible with the OpenAI chat API for assisted solving;

• Tesseract, only for local OCR;

• Docker and local images, only for run_code;

• pypdf, only for PDF extraction.

Basic installation:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Optional extras:

pip install -e ".[sdk]"   # Python SDK oficial do MCP
pip install -e ".[math]"  # SymPy
pip install -e ".[pdf]"   # pypdf

Configuration

Copy .env.example to .env and fill in only the providers you wish to use. The .env file must not be versioned or shared.

LLM solving

QUAESTIO_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_LLM_API_KEY=...
QUAESTIO_LLM_MODEL=...
QUAESTIO_LLM_TIMEOUT_SECONDS=45

This is the main backend. If the second backend is fully configured, Quaestio runs consensus:

QUAESTIO_SECONDARY_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_SECONDARY_LLM_API_KEY=...
QUAESTIO_SECONDARY_LLM_MODEL=...

Without a backend, the server remains available, but questions that cannot be solved deterministically return needs_review.

Language preparation

QUAESTIO_TRANSLATION_MODE=auto
QUAESTIO_TRANSLATION_TARGET_LANGUAGE=en
QUAESTIO_TRANSLATOR_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_TRANSLATOR_API_KEY=...
QUAESTIO_TRANSLATOR_MODEL=...
QUAESTIO_TRANSLATOR_TIMEOUT_SECONDS=30
QUAESTIO_TRANSLATION_OCR=auto
QUAESTIO_TRANSLATION_OCR_LANGUAGE=por+eng

Available modes:

• never: never translates;

• auto: translates when the question is not in English;

• required: requires the translator when translation is necessary.

The original image is not changed. When OCR is present, the recognized text can be used as auxiliary context, but the image is still sent as visual evidence.

Semantic search

QUAESTIO_KNOWLEDGE_BASE_PATH=./data/knowledge.json
QUAESTIO_EMBEDDING_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_EMBEDDING_API_KEY=...
QUAESTIO_EMBEDDING_MODEL=...
QUAESTIO_EMBEDDING_TIMEOUT_SECONDS=30

Embeddings are optional. When unavailable, the local base uses TF-IDF. The base stores materials and vectors locally; do not add content that cannot be persisted in that file.

Independent semantic verification

QUAESTIO_VERIFIER_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_VERIFIER_LLM_API_KEY=...
QUAESTIO_VERIFIER_LLM_MODEL=...
QUAESTIO_VERIFIER_LLM_TIMEOUT_SECONDS=45

This backend should be separate from the solver when review independence is important. It returns supports, contradicts, or uncertain; it does not turn an LLM answer into verified.

Optional local resources

QUAESTIO_TESSERACT_PATH=
QUAESTIO_DOCKER_PATH=
QUAESTIO_SANDBOX_PYTHON_IMAGE=python:3.12-slim

The Docker sandbox does not download images automatically. The images must exist locally.

How to start the server

After an editable installation:

quaestio

Without an editable installation:

$env:PYTHONPATH = "src"
python -m quaestio.mcp_server

The process appears to be waiting for input because the stdio transport is driven by the MCP client. This is the expected behavior.

Configuration in an MCP client

An MCP host needs to start the server command as a subprocess. Generic example for Windows:

{
  "mcpServers": {
    "quaestio": {
      "command": "C:\\caminho\\para\\Quaestio\\.venv\\Scripts\\quaestio.exe"
    }
  }
}

Alternatively, using Python:

{
  "mcpServers": {
    "quaestio": {
      "command": "C:\\caminho\\para\\Quaestio\\.venv\\Scripts\\python.exe",
      "args": ["-m", "quaestio.mcp_server"],
      "env": {
        "PYTHONPATH": "C:\\caminho\\para\\Quaestio\\src"
      }
    }
  }
}

Environment variables can be provided by the local .env or by the host configuration. Prefer the host's secret mechanism when available and never include real keys in the repository.

MCP tools

Solving and verification

Materials and retrieval

Parsing, OCR, and documents

For visual processing and OCR, the input must contain an inline base64 image. URI references are accepted in the canonical contract, but the current OCR and multimodal sending flow uses the inline bytes.

Code

run_code does not execute code on the host. If Docker, image, or language is unavailable, it returns a structured unavailability state.

Diagnostics

Input contract

A canonical question can be sent as follows:

{
  "question": "Qual é a capital do Brasil?",
  "options": ["Rio de Janeiro", "Brasília", "São Paulo"],
  "question_id": "q-001",
  "context": "Questão de geografia.",
  "attachments": []
}

Main fields:

• question: required text;

• options: optional list with at least two unique alternatives;

• question_id: identifier preserved in batches;

• context: additional context or retrieved material;

• attachments: images or documents, usually with mime_type and data_base64;

• expected_answer and expected_option_index: only for evaluation with an answer key, not to guide the solver.

Output contract

A response contains, among other fields:

{
  "question_type": "multiple_choice",
  "answer": "Brasília",
  "option_index": 1,
  "confidence": 0.75,
  "status": "answered",
  "method": "consensus",
  "verification": {
    "status": "answered",
    "verified": false,
    "semantic": {
      "status": "supports",
      "confidence": 0.91
    }
  },
  "sources": [],
  "warnings": [],
  "trace": []
}

Response status

• verified: sufficient deterministic evidence;

• answered: a proposal was produced, but there is no deterministic proof;

• needs_review: consensus, evidence, or validation was missing;

• error: pipeline failure.

The correct field is only populated when the client provides an answer key via expected_answer or expected_option_index.

Example MCP call

After server/discover, the client can call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "example-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "solve_question",
    "arguments": {
      "question": "Qual é a capital do Brasil?",
      "options": ["Rio de Janeiro", "Brasília", "São Paulo"]
    }
  }
}

The MCP result includes serialized textual content and structuredContent for clients that support structured results.

Development and validation

Run the automated suite with:

pytest -q

Unit tests must be executed without relying on real calls to providers. Smoke tests against external APIs must be explicit, using local credentials and authorized questions.

Related technical documentation:

• specification and plan for multilingual preparation / plan;

• test isolation specification / plan;

• NIM smoke test specification / plan;

• multimodal evaluation specification / plan;

• embeddings specification / plan;

• multimodal verifier specification / plan;

• benchmark and confidence specification / plan.

Current limitations

• public HTTP transport is not yet implemented;

• the server does not expose MCP resources or prompts;

• the semantic verifier accepts inline images; external URIs, PDFs, and video are not yet sent at this stage;

• the embeddings index requires reindexing when the configured model is changed;

• OCR and PDF extraction rely on optional local installations;

• consensus and semantic review reduce risk, but do not replace answer key, formal proof, or human review.