thewardn-mcp

WARDN Governance wrapper for MCP servers — every Claude tool call, governed.

When Claude Desktop connects to an MCP server (Google Drive, GitHub, Slack, filesystem, etc.), it can call any tool autonomously with no oversight. thewardn-mcp sits between Claude and your real MCP servers. Every tool call passes through TheWARDN's governance engine before it reaches the actual service. BLOCKED calls never execute. HELD calls go into escrow for human review. CLEARED calls are forwarded transparently.

---

How it works

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.)

Every tool call goes through TheWARDN's CHAM (Contextual Harm Assessment Module) policy engine. Verdicts are sealed, immutable, and logged in the WARDN audit chain. Escrow holds surface in the WARDN console at console.thewardn.ai for administrator review.

---

Installation

pip install thewardn-mcp

Requires Python 3.10+.

---

Quick start

Step 1: Initialize your config

wardn-mcp init

This walks you through entering your WARDN API key, agent ID, and the downstream MCP servers you want to govern. Config is saved to ~/.wardn/mcp-config.json.

Get your API key and agent ID from console.thewardn.ai/settings.

Step 2: Add to Claude Desktop

Edit ~/.claude/claude_desktop_config.json:

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

Step 3: Restart Claude Desktop

All tools from your governed MCP servers will now appear in Claude prefixed with their server name (e.g., google-drive__create_file, github__create_repository). Every call is governed.

---

Configuration

Config file location: ~/.wardn/mcp-config.json (override with WARDN_MCP_CONFIG env var or --config flag).

{
  "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"
  }
}

Fields

Field	Required	Description
wardn_api_key	Yes	Your WARDN API key (wdn_live_...)
wardn_base_url	No	Defaults to https://api.thewardn.ai
agent_id	Yes	The WARDN agent ID representing Claude
servers	Yes	List of downstream MCP servers to govern
tool_overrides	No	Per-tool bypass rules (see below)

Tool overrides

Override governance for specific tools without a round-trip to the API:

• "always_block" — permanently block this tool regardless of WARDN policy
• "always_clear" — bypass governance for this tool (use for read-only or low-risk tools)

Overrides match on the base tool name (without server prefix) or the full governed name (server__tool).

---

Governance verdicts

Verdict	Behavior
CLEARED	Tool call forwarded to the real MCP server
HELD	Tool call blocked pending administrator approval in WARDN console
BLOCKED	Tool call rejected immediately; Claude receives a block message

When a tool is HELD, Claude receives an escrow ID and a link to the WARDN console. An administrator can approve or reject the action at console.thewardn.ai.

---

CLI reference

# 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]

---

Tool naming

Tools from downstream servers are namespaced to avoid collisions:

{server_name}__{original_tool_name}

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

Tool descriptions shown to Claude include a [WARDN GOVERNED] prefix so it is clear governance is active.

---

Fail-open behavior

If the WARDN API is unreachable (network error, timeout, non-200 response), the governance client logs a warning and fails open — the tool call is treated as CLEARED. This prevents governance infrastructure outages from blocking all Claude activity.

To change this to fail-closed, override govern_tool in a subclass of WARDNGovernClient.

---

Using programmatically

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())

---

Governance flow diagram

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

---

Documentation

Full documentation: docs.thewardn.ai

WARDN console (manage policies, review escrow, view audit logs): console.thewardn.ai

---

License

MIT