thewardn-mcp

Wrapper de gobernanza WARDN para servidores MCP: cada llamada a herramientas de Claude, gobernada.

Cuando Claude Desktop se conecta a un servidor MCP (Google Drive, GitHub, Slack, sistema de archivos, etc.), puede llamar a cualquier herramienta de forma autónoma sin supervisión. thewardn-mcp se sitúa entre Claude y tus servidores MCP reales. Cada llamada a una herramienta pasa por el motor de gobernanza de TheWARDN antes de llegar al servicio real. Las llamadas BLOCKED nunca se ejecutan. Las llamadas HELD pasan a un depósito en garantía para revisión humana. Las llamadas CLEARED se reenvían de forma transparente.

Cómo funciona

Claude Desktop
      |
      | (MCP protocol over stdio)
      v
wardn-mcp governance server    <-- this package
      |
      | POST /tool/govern  →  api.thewardn.ai
      |     verdict: CLEARED / HELD / BLOCKED
      |
      | (if CLEARED)
      v
Real MCP server (Google Drive, GitHub, etc.)

Cada llamada a una herramienta pasa por el motor de políticas CHAM (Módulo de Evaluación de Daños Contextuales) de TheWARDN. Los veredictos se sellan, son inmutables y se registran en la cadena de auditoría de WARDN. Las retenciones en depósito aparecen en la consola de WARDN en console.thewardn.ai para revisión del administrador.

Instalación

pip install thewardn-mcp

Requiere Python 3.10+.

Inicio rápido

Paso 1: Inicializa tu configuración

wardn-mcp init

Esto te guiará a través de la introducción de tu clave API de WARDN, el ID del agente y los servidores MCP descendentes que deseas gobernar. La configuración se guarda en ~/.wardn/mcp-config.json.

Obtén tu clave API y el ID del agente en console.thewardn.ai/settings.

Paso 2: Añadir a Claude Desktop

Edita ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wardn-governed": {
      "command": "wardn-mcp",
      "args": ["start"],
      "env": {
        "WARDN_MCP_CONFIG": "~/.wardn/mcp-config.json"
      }
    }
  }
}

Paso 3: Reinicia Claude Desktop

Todas las herramientas de tus servidores MCP gobernados aparecerán ahora en Claude con el prefijo del nombre de su servidor (por ejemplo, google-drive__create_file, github__create_repository). Cada llamada está gobernada.

Configuración

Ubicación del archivo de configuración: ~/.wardn/mcp-config.json (se puede sobrescribir con la variable de entorno WARDN_MCP_CONFIG o el flag --config).

{
  "wardn_api_key": "wdn_live_...",
  "wardn_base_url": "https://api.thewardn.ai",
  "agent_id": "agt_...",
  "servers": [
    {
      "name": "google-drive",
      "command": ["npx", "-y", "@modelcontextprotocol/server-gdrive"],
      "args": [],
      "env": {
        "GDRIVE_CREDENTIALS_FILE": "~/.wardn/gdrive-credentials.json"
      }
    },
    {
      "name": "github",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  ],
  "tool_overrides": {
    "delete_repository": "always_block",
    "list_files": "always_clear"
  }
}

Campos

Omisiones de herramientas (Overrides)

Sobrescribe la gobernanza para herramientas específicas sin un viaje de ida y vuelta a la API:

• "always_block" — bloquea permanentemente esta herramienta independientemente de la política de WARDN

• "always_clear" — omite la gobernanza para esta herramienta (úsalo para herramientas de solo lectura o de bajo riesgo)

Las omisiones coinciden con el nombre base de la herramienta (sin el prefijo del servidor) o con el nombre gobernado completo (server__tool).

Veredictos de gobernanza

Cuando una herramienta está HELD, Claude recibe un ID de depósito en garantía y un enlace a la consola de WARDN. Un administrador puede aprobar o rechazar la acción en console.thewardn.ai.

Referencia de CLI

# Start the governance server
wardn-mcp start [--config PATH]

# Initialize config interactively
wardn-mcp init [--config PATH]

# Show current config and downstream server status
wardn-mcp status [--config PATH]

Nomenclatura de herramientas

Las herramientas de los servidores descendentes tienen nombres con espacios de nombres para evitar colisiones:

{server_name}__{original_tool_name}

# Examples:
google-drive__list_files
google-drive__create_file
github__create_repository
github__search_code
slack__send_message

Las descripciones de las herramientas que se muestran a Claude incluyen un prefijo [WARDN GOVERNED] para que quede claro que la gobernanza está activa.

Comportamiento de fallo abierto (Fail-open)

Si la API de WARDN no está accesible (error de red, tiempo de espera, respuesta distinta de 200), el cliente de gobernanza registra una advertencia y falla en abierto: la llamada a la herramienta se trata como CLEARED. Esto evita que las interrupciones de la infraestructura de gobernanza bloqueen toda la actividad de Claude.

Para cambiar esto a fallo cerrado (fail-closed), sobrescribe govern_tool en una subclase de WARDNGovernClient.

Uso programático

import asyncio
from wardn_mcp import WARDNGovernanceMCPServer, WARDNMCPConfig, MCPServerConfig

config = WARDNMCPConfig(
    wardn_api_key="wdn_live_...",
    agent_id="agt_...",
    servers=[
        MCPServerConfig(
            name="github",
            command=["npx", "-y", "@modelcontextprotocol/server-github"],
            env={"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."},
        )
    ],
)

server = WARDNGovernanceMCPServer(config)
asyncio.run(server.run())

Diagrama de flujo de gobernanza

Claude calls tool: google-drive__delete_file(path="/budget.xlsx")
          |
          v
wardn_mcp intercepts call
          |
          v
Check tool_overrides: no override for delete_file
          |
          v
POST api.thewardn.ai/tool/govern
  {
    agent_id: "agt_...",
    tool_name: "delete_file",
    tool_input: {path: "/budget.xlsx"},
    integration: "google-drive"
  }
          |
          v
  WARDN CHAM evaluates:
  - Policy rules for this agent
  - Risk tier of delete_file
  - Context: what files have been accessed this session
  - Integration-level rules for google-drive
          |
       -------
      |       |
   CLEARED   BLOCKED / HELD
      |            |
      v            v
Forward to    Return verdict message to Claude
Google Drive  (+ escrow ID if HELD)
MCP server

Documentación

Documentación completa: docs.thewardn.ai

Consola WARDN (gestionar políticas, revisar depósitos en garantía, ver registros de auditoría): console.thewardn.ai

Licencia

MIT