MCP Server Mode

Configuration

Add MCP Guard to your IDE's MCP configuration:

{
  "mcpServers": {
    "mcpguard": {
      "command": "npx",
      "args": ["-y", "mcpguard"]
    }
  }
}

Available MCP Tools

Transparent Proxy Tools

When MCPGuard discovers your other MCPs, their tools become available with namespaced names:

github::search_repositories
github::create_issue
filesystem::read_file
weather::get_forecast

• Schemas are loaded on-demand when tools are called
• All tool calls route through secure isolation
• Results returned transparently to the AI

MCP Prompts Support

MCPGuard also supports MCP Prompts - pre-defined message templates that appear as slash commands in your IDE (e.g., /mcpguard/github:AssignCodingAgent).

What are prompts? Prompts are read-only templates that return messages to inject into the chat context. Unlike tools (which execute actions), prompts simply provide pre-formatted text, making them useful for common workflows like "assign a coding agent to this issue" or "create a fix workflow."

Why don't prompts need worker isolation? Prompts don't execute any code - they just return pre-defined messages. This makes them safe by design, so MCPGuard proxies them directly to the underlying MCP without the overhead of worker isolation. Only tools that execute actions require the security of worker isolates.

Example prompts:

mcpguard/github:AssignCodingAgent
mcpguard/github:issue_to_fix_workflow

The mcpguard/github: prefix shows these are GitHub MCP prompts routed through MCPGuard's transparent proxy.

MCPGuard Management Tools

Transparent Proxy Mode

By default, MCPGuard operates in transparent proxy mode:

1. Discovers all MCPs configured in your IDE (even disabled ones)
2. Lazy-loads tool schemas only when tools are actually called
3. Routes all tool calls through secure Worker isolation
4. Auto-loads MCPs when their tools are first used

Example Flow

When the AI calls github::search_repositories:

1. MCPGuard intercepts the namespaced call
2. If GitHub MCP isn't loaded, it's automatically loaded
3. The call executes in a secure Worker isolate
4. Results return to the AI transparently

Direct Code Execution

For complex operations, use the call_mcp tool:

// AI writes code that runs in isolation
const repos = await mcp.search_repositories({ query: 'typescript' });
const summary = repos.slice(0, 5).map(r => `${r.name}: ${r.stars} stars`);
console.log(summary.join('\n'));

Benefits:

• Process large datasets in the sandbox
• Return only summarized results
• Reduce context window usage by up to 98%

Development Mode

For local development:

# Start in development mode
npm run dev

Then configure your AI agent to use the local server:

{
  "mcpServers": {
    "mcpguard": {
      "command": "node",
      "args": ["/path/to/mcpguard/dist/server/index.js"]
    }
  }
}

Best Practices

Disable Other MCPs

For maximum efficiency and security:

{
  "mcpServers": {
    "mcpguard": {
      "command": "npx",
      "args": ["-y", "mcpguard"]
    },
    "github": {
      "disabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

• MCPGuard still discovers disabled MCPs
• Tool calls route through secure isolation
• No duplicate tool loading in context window

Use Code Mode for Complex Tasks

Instead of multiple tool calls:

// Traditional: 5 separate tool calls
search_repositories → 25,000 tokens
get_repository → 5,000 tokens
list_issues → 10,000 tokens
...

Use code mode:

// Single call_mcp call: ~750 tokens
const repos = await mcp.search_repositories({ query: 'test' });
const filtered = repos.filter(r => r.stars > 100);
console.log(`${filtered.length} popular repos found`);

Monitor with Metrics

Check performance with get_metrics:

{
  "total_executions": 150,
  "successful_executions": 148,
  "failed_executions": 2,
  "average_execution_time_ms": 234,
  "total_mcp_calls": 523,
  "estimated_tokens_saved": 45000
}