MCP Guard

Starting the CLI

# Using npx (no installation required)
npx mcpguard
 
# Or if installed locally
npm run cli

You'll see the interactive prompt:

╔═══════════════════════════════════════════════════════════╗
║              MCP Guard - Interactive CLI                  ║
╚═══════════════════════════════════════════════════════════╝

Type "help" for available commands.
Type "exit" to quit.

mcpguard>

Available Commands

Command	Description
`status`	Show at-a-glance MCP Guard status (counts, token savings, quick actions)
`savings`	Detailed token savings analysis with per-MCP breakdown
`guard <mcp>`	Enable MCPGuard protection for an MCP (use `--all` for all MCPs)
`unguard <mcp>`	Disable MCPGuard protection for an MCP (use `--all` for all MCPs)
`network <mcp> on\|off`	Enable/disable Worker outbound network for a guarded MCP
`allowhost <mcp> add\|remove <host>`	Add/remove an allowed host (e.g., `api.github.com`)
`allowlocalhost <mcp> on\|off`	Allow/deny localhost access (`localhost`/`127.0.0.1`)
`configure`	View security configuration for an MCP
`diagnose`	Step-by-step connection diagnostics for an MCP
`load`	Load an MCP server (shows saved configs, auto-saves new ones)
`test`	Interactively test MCP tools (select tool, enter args, execute via Wrangler)
`test-direct`	Test MCP directly without Wrangler/Worker isolation (uses saved configs)
`execute`	Execute custom TypeScript code against a loaded MCP
`list`	List all loaded MCP servers
`saved`	List all saved MCP configurations
`delete`	Delete a saved MCP configuration
`schema`	Get TypeScript API schema for an MCP
`unload`	Unload an MCP server and clean up
`conflicts`	Check for IDE MCP configuration conflicts
`metrics`	Show performance metrics
`help`	Show help message
`exit`	Exit the CLI

Network Access Commands

MCP Guard can enforce an outbound network policy for code executed inside Worker isolates. This is disabled by default and can be enabled per MCP using an allowlist.

Scope

These commands affect code execution inside MCP Guard’s Worker isolate. They do not modify your IDE’s MCP server definitions.

Enable/Disable Network

mcpguard> network github on
mcpguard> network github off

Allowlist Hosts

mcpguard> allowhost github add api.github.com
mcpguard> allowhost github remove api.github.com

Allow Localhost

mcpguard> allowlocalhost github on
mcpguard> allowlocalhost github off

Common Workflows

Quick Status Check

mcpguard> status

Shows:

Number of MCPs discovered
Protection status
Token savings estimate
Quick action suggestions

Protect All MCPs

mcpguard> guard --all

Enables MCPGuard protection for all discovered MCPs, maximizing token savings and security.

View Token Savings

mcpguard> savings

Shows detailed breakdown of token savings per MCP, including:

Current token usage
Estimated savings with MCPGuard
Percentage reduction

Testing with GitHub MCP

Start the CLI

npx mcpguard

Load the GitHub MCP Server

mcpguard> load
MCP name: github
Command (e.g., npx): npx
Args (comma-separated): -y,@modelcontextprotocol/server-github
Environment variables as JSON: {"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_your_token"}

Loading MCP server...

Check What Was Loaded

mcpguard> list

You'll see your loaded MCP server with its ID, status, and available tools.

Get the TypeScript API Schema

mcpguard> schema

Enter the MCP ID from the previous step. You'll see TypeScript API definitions generated from the MCP tools.

Execute Code

mcpguard> execute

Enter the MCP ID and TypeScript code:

// Search for repositories
const repos = await mcp.search_repositories({ query: 'typescript' });
console.log(`Found ${repos.length} repositories`);

View Metrics

mcpguard> metrics

Shows:

Total executions
Success rate
Average execution time
Estimated tokens saved

Clean Up

mcpguard> unload

Enter the MCP ID to clean up resources.

Code Execution Examples

Simple Test

console.log('Hello from Worker isolate!');
const result = { message: 'Test successful', timestamp: Date.now() };
console.log(JSON.stringify(result));

Using MCP Tools

// Search GitHub repositories
const repos = await mcp.search_repositories({ 
  query: 'cloudflare workers',
  page: 1 
});
 
// Process results in the isolate
const summary = repos.map(r => ({
  name: r.name,
  stars: r.stargazers_count
}));
 
// Only return the summary (not all raw data)
console.log(JSON.stringify(summary, null, 2));

Chaining Operations

// Get user info
const user = await mcp.get_user({ username: 'octocat' });
 
// Get their repositories
const repos = await mcp.list_user_repos({ 
  username: user.login,
  per_page: 5 
});
 
// Summarize
console.log(`${user.name} has ${user.public_repos} repos`);
console.log('Top 5:', repos.map(r => r.name).join(', '));

Verbose Mode

For debugging, use the -v or --verbose flag:

npx mcpguard --verbose

This shows detailed logs including:

MCP process startup
Wrangler dev server status
RPC server communication
Worker execution details

Environment Setup

Create a .env file in your project root:

# Required for GitHub MCP
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxx
 
# Optional: Enable debug logging
LOG_LEVEL=debug

Environment Variable Names

Each MCP server expects specific environment variable names. Check the MCP's documentation for required variables. For GitHub MCP, use GITHUB_PERSONAL_ACCESS_TOKEN.

Saved Configurations

MCP Guard saves your MCP configurations for easy reuse:

mcpguard> saved

Lists all saved configurations with:

MCP name
Command and arguments
Environment variable placeholders (actual values not stored)

Saved configs use ${VAR_NAME} placeholders for environment variables, so your secrets stay in .env files.

CLI Usage