Skip to main content
Glama
wganalytics

mcp-secure-server-giulia-ai

by wganalytics
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

PRJ-05 — Servidor MCP Seguro (autenticação por API Key)

Servidor MCP (FastMCP, transporte stdio) cujas tools só executam mediante uma API Key válida. As chaves são geradas com secrets.token_urlsafe, hasheadas com bcrypt e guardadas em SQLite; a validação usa bcrypt.checkpw. Senhas de usuário também são hasheadas com bcrypt. Corresponde ao Capítulo 6 do livro Model Context Protocol (Sandeco).

Arquitetura

database.py    → SQLite (tabelas users, api_keys) — grava em data/database.db
repository.py  → UserRepository / APIKeyRepository (SQL parametrizado)
generate_api_key.py → par (segredo, hash bcrypt)
api_key_controller.py → orquestra geração/validação/máscara de chaves
server_seguro.py → tools MCP protegidas (tool_segura, listar_usuarios)
main.py        → CLI de bootstrap (create-user / gen-key / list-users)

Formato da chave pública: sk-{user_id}-{secret} (só o hash do segredo é persistido).

Related MCP server: Credential Manager MCP Server

Uso

uv sync

# 1) cria um usuário (senha hasheada com bcrypt)
uv run python src/main.py create-user --name "Giulia" --email giulia@ex.com --password ***

# 2) gera a API Key (exibida UMA vez)
uv run python src/main.py gen-key --user-id 1 --name "chave-dev"

# 3) configure a chave no ambiente
cp .env.example .env   # e cole a full key em GIULIA_AI_API_KEY

# 4) sobe o servidor MCP
uv run python src/server_seguro.py

Com a chave configurada, a tool tool_segura retorna uma saudação com os dados do usuário autenticado; sem chave (ou inválida), toda tool lança API Key inválida.

Segurança

  • Segredos hasheados (bcrypt + salt), nunca em texto puro no banco.

  • SQL sempre parametrizado (sem injeção).

  • Chave exibida uma única vez; no banco fica só a versão mascarada + hash.

  • .env e data/*.db fora do controle de versão (ver .gitignore).

Custo da validação

Cada chave guarda dois derivados: o hash bcrypt (o verificador) e um lookup_hash (SHA-256, apenas um índice). A validação localiza a linha exata pelo índice e roda bcrypt.checkpw uma vez. Antes o bcrypt rodava contra todas as chaves do usuário até casar — O(n) numa função que é lenta de propósito.

SHA-256 puro seria fraco para senha, mas o segredo aqui tem 32 bytes de secrets.token_urlsafe: não há dicionário que ataque isso. É o mesmo desenho usado por provedores de API em produção — índice rápido para achar, verificador lento para confirmar. Bancos criados antes da coluna existir são migrados automaticamente, e as chaves antigas continuam válidas.

Limitação: isto não autentica o chamador

A tool lê a chave de os.getenv("GIULIA_AI_API_KEY") — do ambiente do próprio servidor, não de um parâmetro enviado pelo cliente.

Em stdio o servidor MCP é um processo filho do cliente: um processo, um cliente. Não existe "outro chamador" para distinguir — a fronteira de confiança é o sistema operacional, não o protocolo. O que este projeto entrega é credencial bem guardada + um gate de configuração.

Autenticação de chamador só passa a fazer sentido com transporte HTTP, com a chave viajando na requisição. Essa camada não está implementada aqui.

Testes

uv run pytest        # 33 testes, contra SQLite temporário

Cobrem o formato da chave, o não-vazamento do segredo no arquivo do banco, o mascaramento, a validação (incluindo chave de outro usuário), a contagem de chamadas ao bcrypt, a migração do lookup_hash e a revogação.

Available Tools

2 tools
listar_usuariosA

Lista todos os usuários cadastrados no sistema. Retorna nome e email de cada usuário.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that the tool returns name and email for each user, making it clearly a read-only listing operation. But it does not mention authentication needs, pagination behavior, ordering, or possible failure modes, which would strengthen transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The primary action is front-loaded, and the return fields are stated immediately. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, simple listing tool, the description is complete: it states what is listed and what is returned. The presence of an output schema further covers return details, and there are no required parameters or nested objects that need explanation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero properties, and the description correctly adds no confusing parameter information. With 0 parameters, the baseline is 4 because there is nothing for the description to compensate for. The description appropriately focuses on the operation and output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Lista todos os usuários cadastrados no sistema.' It clearly states the tool's scope (all registered users) and tells the agent what data is returned (name and email). This is unambiguous and distinguishes the tool by domain from its sibling tool_segura.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when you need all registered users and their names/emails. However, it does not explicitly state when not to use it, nor does it mention tool_segura or any alternative conditions. The guidance is adequate but left mostly to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_seguraA

Valida a API Key e retorna uma saudação com os dados do usuário autenticado.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It discloses that the tool validates an API key and returns a greeting, implying a read-only/validation operation, but does not mention error handling, side effects, or how invalid keys are treated. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no redundant information; every word contributes to the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter tool with an output schema, the description covers the core behavior and the output is documented elsewhere. It lacks explicit error-handling or authentication-header details, but these are minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the input schema is empty (100% coverage). The description adds context that an API key is validated, which clarifies why no parameters are needed. Baseline is 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Valida a API Key') and a clear outcome ('retorna uma saudação com os dados do usuário autenticado'), which distinguishes it from the sibling 'listar_usuarios' that lists users. An agent can understand exactly what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (validate API key and get authenticated user's greeting) but does not explicitly contrast with 'listar_usuarios' or state when to choose one over the other. There is no exclusion or alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedlistar_usuarios
    • First observedtool_segura
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

Each tool targets a distinct function: one validates the API key and authenticates the user, the other lists all users. There is no overlap or ambiguity between them.

Naming Consistency2/5

The tool names are inconsistent: 'tool_segura' uses a vague 'tool_' prefix with a non-verbal name, while 'listar_usuarios' follows a clear verb_noun pattern. This mixed convention makes the set feel uncoordinated.

Tool Count3/5

Two tools is at the low end of the acceptable range. It is understandable for a limited server, but the small count feels thin relative to the 'secure server' positioning.

Completeness2/5

The server covers authentication validation and listing users, but lacks user management operations such as get by ID, create, update, or delete. This creates significant gaps in the implied user management domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • ServeMyAPI

    Jktfe
    F
    license
    Not graded
    quality
    D
    maintenance
    A personal MCP server for securely storing and accessing API keys across projects using the macOS Keychain, letting AI assistants and applications retrieve credentials through natural language.
    25
    -

  • Credential Manager MCP Server

    mclamee
    A
    license
    Not graded
    quality
    C
    maintenance
    A secure MCP server for local API credential management using JSON storage and a read-only default mode. It allows users to list, retrieve, and manage credentials via simple command-line tools and environment-based configuration.
    MIT

  • MCP Server with Authentication

    ahmad-act
    A
    license
    C
    quality
    D
    maintenance
    Implements a secure MCP server with API Key and JWT authentication, providing tools like echo, login, secure_action, and admin_action. Includes MCP Inspector integration for testing and debugging.
    1
    3
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wganalytics/mcp-secure-server-giulia-ai'

If you have feedback or need assistance with the MCP directory API, please join our Discord server