API

This MCP (Memory, Controller, Policy) server organizes a generation-augmented search system by separating memory, business rules, and request orchestration. It enables scalable, maintainable integration with a vector store and a language model, so you can query documents, apply governance rules, and obtain coherent, context-aware answers.

How to use

You interact with the MCP server by running the back-end service and calling its HTTP API. The server exposes a /mcp/ask endpoint through a FastAPI-based layer. You can access its interactive API docs at the local URL where the server is running, and you can supply a question along with optional parameters to retrieve context-enhanced responses.

How to install

Prerequisites: Python 3.9 or later. A Pinecone account with an API key. A Google Gemini API key.

# Create a virtual environment
python -m venv venv

# Activate the environment
# Windows (PowerShell)
.\venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables in a .env file
# Example shown below
PINECONE_API_KEY="SUA_CHAVE_PINECONE"
PINECONE_HOST="SEU_HOST_PINECONE"
PINECONE_INDEX_NAME="brito-ai"
GEMINI_API_KEY="SUA_CHAVE_GEMINI"

# Run the backend (development server)
uvicorn api_mcp:app --reload --host 0.0.0.0 --port 8000

# (Optional) Run the frontend if present
cd frontend
npm run dev

Configuration and running notes

The server uses three MCP layers: Memory (data and long-term state), Policy (business rules and validations), and Controller (request orchestration). The backend serves the MCP API at a local address and provides a documentation UI for testing.

# HTTP MCP config example (documented runtime endpoint)
{
  "mcpServers": {
    "api_http_mcp": {
      "type": "http",
      "name": "api_http_mcp",
      "url": "http://127.0.0.1:8000/docs",
      "args": []
    }
  }
}

Examples and tips

Start your back-end locally using the standard development command shown earlier, then use the /mcp/ask endpoint to pose questions. The system searches memory, applies policies to filter and validate results, and generates a structured answer using Gemini. You can adjust max_results to constrain the number of relevant documents considered for the final response.

Available tools

Memory layer

Manages long-term state and interactions with the vector store (Pinecone). All search and persistence operations pass through this layer.

Policy layer

Applies business rules, validations, and restrictions such as relevance scoring and data access controls.

Controller layer

Orchestrates the request flow, builds prompts, and coordinates the Memory and Policy layers before invoking the Gemini LLM.