MCP Gatekeeper

A security-focused MCP (Model Context Protocol) gateway that enables AI assistants to safely execute shell commands with fine-grained access control.

Why MCP Gatekeeper?

Security First: Multi-layer protection with policy-based argument validation, environment variable filtering, and sandboxing (bubblewrap/WASM)
Flexible Deployment: Run as stdio server for Claude Desktop, HTTP API for web services, or bridge proxy for existing MCP servers
Bridge Mode: Expose any stdio-based MCP server (Playwright, filesystem, etc.) over HTTP with authentication, rate limiting, and large response handling
OAuth 2.0 Ready: Machine-to-machine authentication with client credentials flow (MCP SEP-1046)
Plugin Architecture: Define tools via simple JSON files with glob-based argument patterns
Rich UI Support: Generate interactive HTML interfaces via MCP Apps for command outputs

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP Gatekeeper                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Protocol Layer                                                     │   │
│  │  ├─ Stdio Mode: Direct MCP client integration                       │   │
│  │  ├─ HTTP Mode: JSON-RPC 2.0 with Bearer token auth                  │   │
│  │  └─ Bridge Mode: HTTP proxy to stdio MCP servers                    │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     ↓                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Authentication & Rate Limiting                                     │   │
│  │  ├─ API Key: Simple Bearer token authentication                     │   │
│  │  └─ OAuth 2.0: Client credentials flow (M2M)                        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     ↓                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Plugin Configuration                                               │   │
│  ├─────────────────────────────────────────────────────────────────────┤   │
│  │                                                                     │   │
│  │  Allowed Env Variables: ["PATH", "HOME", "LANG", "GIT_*"]           │   │
│  │                                                                     │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │  Tool: "git-status"                                         │   │   │
│  │  │  ├─ Command: git                                            │   │   │
│  │  │  ├─ Args Prefix: ["status"]                                 │   │   │
│  │  │  ├─ Allowed Args: ["", "--short"]                           │   │   │
│  │  │  ├─ Sandbox: none                                           │   │   │
│  │  │  └─ UI Type: log                                            │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  │                                                                     │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │  Tool: "ls"                                                 │   │   │
│  │  │  ├─ Command: ls                                             │   │   │
│  │  │  ├─ Allowed Args: ["-la", "*"]                              │   │   │
│  │  │  ├─ Sandbox: bubblewrap                                     │   │   │
│  │  │  └─ UI Type: log                                            │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  │                                                                     │   │
│  │  ┌─────────────────────────────────────────────────────────────┐   │   │
│  │  │  Tool: "ruby"                                               │   │   │
│  │  │  ├─ Allowed Args: ["-e **", "*.rb"]                         │   │   │
│  │  │  ├─ Sandbox: wasm                                           │   │   │
│  │  │  └─ WASM Binary: /opt/ruby-wasm/usr/local/bin/ruby          │   │   │
│  │  └─────────────────────────────────────────────────────────────┘   │   │
│  │                                                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     ↓                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Policy Evaluation (glob pattern matching on arguments)             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     ↓                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Command Execution with Sandboxing                                  │   │
│  │  ├─ None: Path validation only                                      │   │
│  │  ├─ Bubblewrap: Linux namespace isolation (bwrap)                   │   │
│  │  └─ WASM: WebAssembly sandbox (wazero runtime)                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                     ↓                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Audit Logging (SQLite) & MCP Apps UI Rendering                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Features

Three Operating Modes: stdio, http, bridge
JSON Plugin Configuration: Define tools via simple JSON files
Flexible Sandboxing: none, bubblewrap, or WASM isolation
Policy-Based Access Control: Glob patterns for argument validation
OAuth 2.0 Authentication: Client credentials flow for M2M communication
MCP Streamable HTTP: Session-based protocol with SSE streaming (2025-06-18)
TUI Admin Tool: Manage OAuth clients via terminal UI
Optional Audit Logging: SQLite-based logging for all modes
Large Response Handling: Automatic file externalization in bridge mode
MCP Apps UI Support: Rich HTML interfaces for tool outputs

Operating Modes

Mode	Use Case
stdio	Direct integration with MCP clients (Claude Desktop, etc.)
http	Expose shell commands as HTTP API
bridge	Proxy existing stdio MCP servers over HTTP

Mode is auto-detected: --addr implies http mode, --upstream implies bridge mode.

Installation

go install github.com/takeshy/mcp-gatekeeper/cmd/server@latest

Or download from Releases.

Quick Start

1. Create a Plugin Directory

Create a directory with plugin.json and optional templates:

my-plugin/
├── plugin.json
└── templates/
    └── custom.html

plugin.json:

{
  "tools": [
    {
      "name": "git-status",
      "description": "Show git repository status",
      "command": "git",
      "args_prefix": ["status"],
      "allowed_arg_globs": ["", "--short", "--branch"],
      "sandbox": "none",
      "ui_type": "log"
    },
    {
      "name": "ls",
      "description": "List directory contents",
      "command": "ls",
      "args_prefix": ["-la"],
      "allowed_arg_globs": ["", "**"],
      "sandbox": "bubblewrap",
      "ui_type": "log"
    }
  ],
  "allowed_env_keys": ["PATH", "HOME", "LANG"]
}

Note: args_prefix defines fixed arguments that are automatically prepended. With args_prefix: ["-la"], calling ls with args: ["/tmp"] executes ls -la /tmp. The allowed_arg_globs validates user-provided args only (not the prefix).

2. Start the Server

Stdio Mode (for MCP clients like Claude Desktop):

./mcp-gatekeeper --mode=stdio \
  --root-dir=/home/user/projects \
  --plugin-file=my-plugin/plugin.json \
  --api-key=your-secret-key

Claude Code Configuration (~/.claude/settings.json):

{
  "mcpServers": {
    "gatekeeper": {
      "command": "/path/to/mcp-gatekeeper",
      "args": [
        "--root-dir", "/home/user/projects",
        "--plugins-dir", "/path/to/plugins"
      ]
    }
  }
}

HTTP Mode:

./mcp-gatekeeper --mode=http \
  --root-dir=/home/user/projects \
  --plugins-dir=plugins/ \
  --api-key=your-secret-key \
  --addr=:8080

Bridge Mode (proxy existing MCP servers):

./mcp-gatekeeper --mode=bridge \
  --upstream='npx @playwright/mcp --headless' \
  --api-key=your-secret-key \
  --addr=:8080

3. Test It

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Execute a tool
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ls","arguments":{"args":["-la"]}}}'

Plugin Configuration

Single Plugin File

./mcp-gatekeeper --plugin-file=my-plugin/plugin.json ...

Plugin Directory (Multiple Plugins)

./mcp-gatekeeper --plugins-dir=plugins/ ...

Supports two formats:

Flat files: plugins/*.json files are loaded directly
Subdirectories: plugins/*/plugin.json directories are loaded

plugins/
├── git/
│   ├── plugin.json
│   └── templates/
│       ├── log.html
│       └── diff.html
├── shell/
│   ├── plugin.json
│   └── templates/
│       └── table.html
└── simple.json          # Flat file also supported

Tool names must be unique across all plugins.

Plugin File Format

{
  "tools": [
    {
      "name": "tool-name",
      "description": "Tool description",
      "command": "/path/to/executable",
      "args_prefix": ["subcommand"],
      "allowed_arg_globs": ["pattern1", "pattern2"],
      "sandbox": "none|bubblewrap|wasm",
      "wasm_binary": "/path/to/binary.wasm",
      "ui_type": "log|table|json",
      "ui_template": "templates/custom.html"
    }
  ],
  "allowed_env_keys": ["PATH", "HOME", "CUSTOM_*"]
}

Field	Required	Description
`name`	Yes	Unique tool name
`description`	No	Tool description
`command`	Yes*	Executable path (*not required for wasm)
`args_prefix`	No	Fixed arguments prepended to user args (e.g., `["-la"]` for ls)
`allowed_arg_globs`	No	Glob patterns for allowed user arguments (evaluated before args_prefix)
`sandbox`	No	`none`, `bubblewrap`, or `wasm` (default: `none`)
`wasm_binary`	Yes*	WASM binary path (*required when sandbox=wasm)
`ui_type`	No	Built-in UI: `table`, `json`, or `log`
`ui_template`	No	Path to custom HTML template (relative to plugin.json)

Note: Template paths are relative to the plugin.json file location. Parent directory references (..) are not allowed for security.

CLI Options

Option	Default	Description
`--mode`	`stdio`	`stdio`, `http`, or `bridge`
`--root-dir`	-	Sandbox root directory (required for stdio/http)
`--plugin-file`	-	Single plugin JSON file
`--plugins-dir`	-	Directory containing plugin directories/files
`--api-key`	-	API key for authentication (or `MCP_GATEKEEPER_API_KEY` env)
`--db`	-	SQLite database path for audit logging and OAuth (optional)
`--enable-oauth`	`false`	Enable OAuth 2.0 authentication (requires `--db`)
`--oauth-issuer`	-	OAuth issuer URL (optional, auto-detected if empty)
`--addr`	`:8080`	HTTP listen address (http/bridge)
`--rate-limit`	`500`	Max requests per minute (http/bridge)
`--upstream`	-	Upstream MCP server command (required for bridge)
`--upstream-env`	-	Environment variables for upstream (comma-separated)
`--max-response-size`	`500000`	Max response size in bytes (bridge)
`--debug`	`false`	Enable debug logging (bridge)
`--wasm-dir`	-	Directory containing WASM binaries
`--enable-streamable`	`false`	Enable MCP Streamable HTTP (2025-06-18)
`--session-ttl`	`30m`	Session TTL for Streamable HTTP

Audit Logging

Enable audit logging by specifying --db:

./mcp-gatekeeper --mode=http --db=audit.db ...

All tools/call requests are logged to the audit_logs table:

Field	Description
`mode`	Server mode (stdio, http, bridge)
`method`	MCP method (e.g., `tools/call`)
`tool_name`	Tool name
`params`	Request parameters (JSON)
`response`	Response (JSON)
`error`	Error message if any
`duration_ms`	Execution time
`created_at`	Timestamp

Query logs:

sqlite3 audit.db "SELECT mode, method, tool_name, duration_ms FROM audit_logs ORDER BY id DESC LIMIT 10"

OAuth 2.0 Authentication

MCP Gatekeeper supports OAuth 2.0 client credentials flow for machine-to-machine (M2M) authentication. This is useful when you need more secure authentication than simple API keys.

Enable OAuth

./mcp-gatekeeper --mode=http \
  --db=gatekeeper.db \
  --enable-oauth \
  --addr=:8080 \
  --plugins-dir=plugins/ \
  --root-dir=/path/to/root

Note: OAuth requires --db to store client credentials and tokens.

Create OAuth Clients

Use the TUI admin tool to create OAuth clients:

./mcp-gatekeeper-admin --db=gatekeeper.db

Navigate to "OAuth Clients" → "New Client" → Enter client ID → Save the generated client secret.

OAuth Flow (Client Credentials)

# 1. Get access token
curl -X POST http://localhost:8080/oauth/token \
  -d "grant_type=client_credentials&client_id=myclient&client_secret=SECRET"

# Response:
# {
#   "access_token": "...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "..."
# }

# 2. Call MCP endpoint
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 3. Refresh token (when access token expires)
curl -X POST http://localhost:8080/oauth/token \
  -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=myclient&client_secret=SECRET"

You can also use HTTP Basic auth for client credentials:

curl -X POST http://localhost:8080/oauth/token \
  -H "Authorization: Basic BASE64(client_id:client_secret)" \
  -d "grant_type=client_credentials"

OAuth Endpoints

Endpoint	Description
`POST /oauth/token`	Token endpoint (client_credentials, refresh_token)
`GET /.well-known/oauth-authorization-server`	OAuth server metadata
`GET /.well-known/openid-configuration`	OpenID Connect discovery
`GET /.well-known/oauth-protected-resource`	Protected resource metadata (RFC 9728)
`GET /.well-known/oauth-protected-resource/{resourcePath}`	Protected resource metadata for a specific path

Token Expiration

Token	Lifetime
Access Token	1 hour
Refresh Token	Unlimited (until client revoked)

Dual Authentication

When both --api-key and --enable-oauth are set, either authentication method is accepted:

Bearer token matching API key
Bearer token from OAuth access token

TUI Admin Tool

The mcp-gatekeeper-admin tool provides a terminal UI for managing OAuth clients.

Installation

# Build from source
make build-admin

# Or install directly
go install github.com/takeshy/mcp-gatekeeper/cmd/admin@latest

Usage

./mcp-gatekeeper-admin --db=gatekeeper.db

Features

OAuth Clients: List, create, revoke, and delete OAuth clients
Audit Logs: View audit log statistics

Keyboard Shortcuts

Key	Action
`j/k` or `↑/↓`	Navigate
`Enter`	Select
`r`	Revoke client
`d`	Delete client
`Esc`	Go back
`q`	Quit

MCP Streamable HTTP

MCP Gatekeeper supports the MCP Streamable HTTP transport (protocol version 2025-06-18), enabling session-based communication with SSE streaming.

Enable Streamable HTTP

# HTTP mode with Streamable HTTP
./mcp-gatekeeper --mode=http \
  --enable-streamable \
  --session-ttl=30m \
  --plugins-dir=plugins/ \
  --root-dir=/path/to/root \
  --addr=:8080

# Bridge mode with Streamable HTTP (separate upstream per session)
./mcp-gatekeeper --mode=bridge \
  --enable-streamable \
  --session-ttl=30m \
  --upstream='npx @playwright/mcp --headless' \
  --addr=:8080

Endpoints

Method	Endpoint	Description
POST	`/mcp`	Send JSON-RPC requests/notifications
GET	`/mcp`	Open SSE stream for server→client notifications
DELETE	`/mcp`	Terminate session

Protocol Flow

# 1. Initialize (creates session)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Response includes Mcp-Session-Id header
# Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000

# 2. Subsequent requests include session ID
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Open SSE stream for server notifications
curl -N http://localhost:8080/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "MCP-Protocol-Version: 2025-06-18"

# 4. Terminate session
curl -X DELETE http://localhost:8080/mcp \
  -H "Mcp-Session-Id: 550e8400-e29b-41d4-a716-446655440000"

Bridge Mode with Streamable HTTP

In bridge mode with --enable-streamable, each session creates its own upstream MCP server process. This provides complete isolation between sessions:

Each initialize request spawns a new upstream process
Session state is not shared between clients
Upstream processes are terminated when sessions expire or are deleted

Bridge Mode Features

File Externalization

Large content (>500KB) in MCP responses is automatically externalized to temporary files:

{
  "type": "external_file",
  "url": "http://localhost:8080/files/abc123...",
  "mimeType": "image/png",
  "size": 1843200
}

Files are deleted after one retrieval (one-time access).

Tip for LLMs: Include this in your prompt when using bridge mode:

When MCP returns {"type":"external_file","url":"...","mimeType":"...","size":...}:
- The content was too large to include directly
- Access the URL via HTTP to retrieve the file (one-time access)
- The file is deleted after retrieval

Sandbox Modes

Mode	Isolation	Use Case
`none`	Path validation only	Trusted commands
`bubblewrap`	Linux namespace isolation	Native binaries (recommended)
`wasm`	WebAssembly sandbox	Complete isolation

Bubblewrap Installation

sudo apt install bubblewrap    # Debian/Ubuntu
sudo dnf install bubblewrap    # Fedora
sudo pacman -S bubblewrap      # Arch

Bubblewrap Mount Directories

When using bubblewrap sandbox, mount point directories are created in --root-dir:

root-dir/
├── bin/      # Read-only mount of /bin
├── dev/      # Minimal device files
├── etc/      # Read-only mount of /etc
├── lib/      # Read-only mount of /lib
├── lib64/    # Read-only mount of /lib64 (if exists)
├── sbin/     # Read-only mount of /sbin (if exists)
├── tmp/      # Temporary filesystem
└── usr/      # Read-only mount of /usr

Note: These directories are created automatically on startup if they don't exist. On shutdown, mcp-gatekeeper automatically removes any empty directories it created (pre-existing directories are not removed).

WASM Setup

Use WASI-compatible binaries. File access is restricted to --root-dir.

# Ruby WASM
tar xzf ruby-*-wasm32-unknown-wasip1-full.tar.gz

# Go (compile your own)
GOOS=wasip1 GOARCH=wasm go build -o tool.wasm main.go

Glob Patterns

Pattern	Description
`""`	Empty string - allows calling with no arguments
`*`	Any string except `/`
`**`	Any string including `/`
`?`	Single character
`[abc]`	Character class
`{a,b}`	Alternation

Examples:

[""] - allows only no arguments (e.g., git status with no args)
["", "--short"] - allows no arguments OR --short
["**"] - allows any arguments (equivalent to omitting allowed_arg_globs)
*.txt - matches any .txt file
--format=* - matches any --format= option

Important: If you want to allow calling a tool with no arguments, you must include "" in allowed_arg_globs. Without it, the tool requires at least one argument.

MCP Apps UI Support

Tools can return interactive UI components instead of plain text. MCP clients like Claude Desktop can display these as rich HTML interfaces.

Built-in UI Types

Type	Description	Best For
`table`	Sortable table	JSON arrays, CSV, command output
`json`	Syntax-highlighted JSON	API responses, config files
`log`	Filterable log viewer	Log files, command output

Plugin Configuration

{
  "name": "git-status",
  "description": "Show git status",
  "command": "git",
  "args_prefix": ["status"],
  "allowed_arg_globs": ["", "*"],
  "sandbox": "none",
  "ui_type": "log"
}

Field	Description
`ui_type`	`table`, `json`, or `log`
`output_format`	`json`, `csv`, or `lines` (for table parsing)
`ui_template`	Path to custom HTML template (overrides ui_type)
`ui_config`	Advanced UI configuration (see below)

UI Configuration

The ui_config field provides fine-grained control over UI behavior:

{
  "name": "file-explorer",
  "description": "Interactive file explorer",
  "command": "ls",
  "args_prefix": ["-la"],
  "allowed_arg_globs": ["", "**"],
  "sandbox": "none",
  "ui_template": "templates/explorer.html",
  "ui_config": {
    "csp": {
      "resource_domains": ["esm.sh"]
    },
    "visibility": ["model", "app"]
  }
}

Field	Description
`csp.resource_domains`	Allowed external domains for CSP (e.g., CDN for MCP App SDK)
`visibility`	Tool visibility: `["model", "app"]` (default) or `["app"]` (app-only)

App-Only Tools

Tools with visibility: ["app"] are hidden from the model but can be called from UI via MCP Apps SDK. This is useful for helper tools that the main UI calls dynamically:

{
  "name": "git-staged-diff",
  "description": "Get staged diff for a file (app-only)",
  "command": "git",
  "args_prefix": ["diff", "--cached", "--"],
  "allowed_arg_globs": ["**"],
  "sandbox": "none",
  "ui_config": {
    "visibility": ["app"]
  }
}

Note: Use ** (not *) in allowed_arg_globs when paths containing / need to be matched.

Custom Templates

Create fully custom UIs with Go templates:

{
  "name": "process-list",
  "command": "ps",
  "args_prefix": ["aux"],
  "ui_template": "templates/process.html"
}

Template variables:

{{.Output}} - Raw output string
{{.Lines}} - Output split by lines (array)
{{.JSON}} - Parsed JSON (if valid)
{{.JSONPretty}} - Pretty-printed JSON
{{.IsJSON}} - Whether output is valid JSON

Template functions:

{{escape .Output}} - HTML escape
{{json .Data}} - JSON encode (returns template.JS for safe embedding)
{{jsonPretty .Data}} - Pretty JSON encode
{{split .String " "}} - Split string by delimiter
{{join .Array " "}} - Join array with delimiter
{{slice .Array 1}} - Slice array from index
{{first .Array}} - Get first element
{{contains .String "text"}} - Check if string contains
{{hasPrefix .String "prefix"}} - Check string prefix
{{trimSpace .String}} - Trim whitespace

Example template:

<!DOCTYPE html>
<html>
<head><title>Process List</title></head>
<body>
  <h1>Processes ({{len .Lines}})</h1>
  <table>
  {{range .Lines}}
  {{if trimSpace .}}
  <tr><td>{{escape .}}</td></tr>
  {{end}}
  {{end}}
  </table>
</body>
</html>

Interactive Templates with MCP Apps SDK

Templates can use the MCP Apps SDK for bidirectional communication, allowing the UI to call other tools dynamically:

<script type="module">
// MCP Apps compatibility layer
// Supports both window.mcpApps (obsidian-gemini-helper) and @anthropic-ai/mcp-app-sdk
let mcpClient = null;

async function initMcpClient() {
  // Check for injected bridge first (obsidian-gemini-helper)
  if (window.mcpApps && typeof window.mcpApps.callTool === 'function') {
    return {
      callServerTool: (name, args) => window.mcpApps.callTool(name, args),
      type: 'bridge'
    };
  }

  // Fall back to MCP App SDK
  try {
    const { App } = await import('https://esm.sh/@anthropic-ai/mcp-app-sdk@0.1');
    const app = new App({ name: 'My App', version: '1.0.0' });
    await app.connect();
    return {
      callServerTool: (name, args) => app.callServerTool(name, args),
      type: 'sdk'
    };
  } catch (e) {
    console.log('MCP App SDK not available:', e.message);
    return null;
  }
}

// Initialize and use
mcpClient = await initMcpClient();
if (mcpClient) {
  // Call an app-only tool
  const result = await mcpClient.callServerTool('git-staged-diff', { args: ['file.txt'] });
  console.log(result.content[0].text);
}

// Initialize data from template
const initialData = {{json .Lines}};  // Safe JS embedding
</script>

Important: When using {{json .Lines}} or similar template functions in JavaScript, the output is automatically safe for embedding (returns template.JS type to prevent double-escaping).

How It Works

tools/list returns tools with _meta.ui.resourceUri for UI-enabled tools
tools/call returns results with _meta.ui.resourceUri containing output data
Client calls resources/read with the URI to get rendered HTML

Example Plugins

See the examples/plugins/ directory:

examples/plugins/
├── git/
│   ├── plugin.json      # Git commands with interactive UI
│   └── templates/
│       ├── changes.html # Interactive staged/unstaged changes viewer
│       ├── commits.html # Interactive commit explorer
│       ├── log.html     # Custom UI for git log
│       └── diff.html    # Custom UI for git diff
├── interactive/
│   ├── plugin.json      # File explorer with bidirectional MCP Apps
│   └── templates/
│       └── explorer.html
└── shell/
    ├── plugin.json      # Shell commands (ls, cat, find, grep)
    └── templates/
        └── table.html   # Custom table UI

Interactive Git Plugin

The git plugin demonstrates bidirectional MCP Apps communication:

git-changes: Shows staged/unstaged files in an accordion UI. Click a file to view its diff (loaded dynamically via app-only tools).
git-commits: Browse commit history. Click a commit to see changed files, click a file to see its diff.

App-only helper tools (visibility: ["app"]):

git-staged-files, git-unstaged-files: List files for the UI
git-staged-diff, git-unstaged-diff: Get diffs for selected files
git-commit-files, git-file-diff: Get commit details

To try the interactive examples:

cd /path/to/your/git/repo
./mcp-gatekeeper --plugins-dir=examples/plugins --root-dir=.

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github/workflows		.github/workflows
cmd		cmd
examples/plugins		examples/plugins
internal		internal
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
README_ja.md		README_ja.md
go.mod		go.mod
go.sum		go.sum
mise.toml		mise.toml
spec.txt		spec.txt

Folders and files

Latest commit

History

Repository files navigation

MCP Gatekeeper

Architecture

Features

Operating Modes

Installation

Quick Start

1. Create a Plugin Directory

2. Start the Server

3. Test It

Plugin Configuration

Single Plugin File

Plugin Directory (Multiple Plugins)

Plugin File Format

CLI Options

Audit Logging

OAuth 2.0 Authentication

Enable OAuth

Create OAuth Clients

OAuth Flow (Client Credentials)

OAuth Endpoints

Token Expiration

Dual Authentication

TUI Admin Tool

Installation

Usage

Features

Keyboard Shortcuts

MCP Streamable HTTP

Enable Streamable HTTP

Endpoints

Protocol Flow

Bridge Mode with Streamable HTTP

Bridge Mode Features

File Externalization

Sandbox Modes

Bubblewrap Installation

Bubblewrap Mount Directories

WASM Setup

Glob Patterns

MCP Apps UI Support

Built-in UI Types

Plugin Configuration

UI Configuration

App-Only Tools

Custom Templates

Interactive Templates with MCP Apps SDK

How It Works

Example Plugins

Interactive Git Plugin

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages