GitGuardian MCP Server

Bring GitGuardian's secret detection and incident management into your AI agent. Scan code for credentials before they leak, triage existing incidents, generate honeytokens, and remediate findings — all from inside your IDE or chat client, backed by GitGuardian's 500+ detectors.

[!CAUTION] MCP servers are an emerging technology. Agents act on your behalf and under your responsibility. Use trusted MCP servers and review agent actions when they interact with tools. To limit blast radius the server defaults to read-only-leaning permissions; what is actually exposed is determined by the OAuth scopes your access token holds.

What it does

• Secret scanning — proactively scan files for leaked credentials.
• Incident management — list, filter, assign, resolve, and tag incidents (both internal and Public Monitoring incidents).
• Honeytokens — generate honeytokens and list existing ones.
• Code-fix automation — open pull requests that remediate secrets in repositories your workspace monitors.

The exact set of tools exposed to your agent depends on the OAuth scopes granted to your access token.

Prompt examples

Scan this codebase for any leaked secrets or credentials.

Remediate all incidents related to my project.

Check if there are any new security incidents assigned to me.

Help me understand this security incident and provide remediation steps.

List all my active honeytokens.

Generate a new honeytoken for monitoring AWS credential access.

Create a honeytoken named 'dev-database' and hide it in config files.

Quick start

The recommended way to run the GitGuardian MCP server is to point your MCP client at the hosted server. The MCP client handles OAuth automatically; no local install, no token to manage, no uvx.

Pick the URL that matches your GitGuardian region:

Region	URL
US SaaS	https://mcp.gitguardian.com/mcp
EU SaaS	https://mcp.eu1.gitguardian.com/mcp
Self-hosted	See Self-hosting the MCP server

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "GitGuardian": {
      "type": "http",
      "url": "https://mcp.gitguardian.com/mcp"
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude Desktop/mcp.json (macOS) or %APPDATA%\Claude Desktop\mcp.json (Windows). Same JSON as Cursor. Claude Desktop versions that pre-date HTTP MCP support need the Local stdio fallback.

Claude.ai (web)

Add the server in Settings → Connectors → Add custom connector with the URL above. OAuth is handled in the browser tab.

Windsurf

Edit ~/Library/Application Support/Windsurf/mcp.json (or ~/.config/Windsurf/mcp.json on Linux):

{
  "mcp": {
    "servers": {
      "GitGuardian": {
        "type": "http",
        "url": "https://mcp.gitguardian.com/mcp"
      }
    }
  }
}

Zed

Edit ~/Library/Application Support/Zed/mcp.json (or ~/.config/Zed/mcp.json on Linux) with the same type: http snippet.

Choosing a deployment

Two deployment paths are supported. Pick based on where your GitGuardian instance lives and what tradeoffs you accept.

Deployment	When to use
Hosted MCP (Quick start above)	GitGuardian SaaS (US/EU) and you accept that requests transit mcp.gitguardian.com in addition to api.gitguardian.com
Self-hosted MCP (§)	Self-hosted GitGuardian, airgapped environments, or you want the MCP server on your own infrastructure
Local stdio with PAT (§)	CI/CD, scripts, one-off invocations, or older MCP clients without type: http support

Authentication

Most users do not need to touch this — the Quick start config implicitly uses the OAuth proxy mode on the hosted server, and the Local stdio config uses PAT env.

There are four authentication modes the server can run in; you pick one via env vars.

Mode	Configuration	Used by
OAuth proxy (HTTP)	MCP_OAUTH_PROXY_ENABLED=true + ENABLE_LOCAL_OAUTH=false	The hosted MCP server. MCP client runs OAuth against /authorize+/token; the server proxies to the GG dashboard.
Raw bearer (HTTP)	ENABLE_LOCAL_OAUTH=false + MCP_PORT set	Self-hosted deployments without OAuth. Client sends Authorization: Bearer <PAT> on every request.
PAT env (any transport)	GITGUARDIAN_PERSONAL_ACCESS_TOKEN=<pat> + ENABLE_LOCAL_OAUTH=false	CI, scripts, local stdio. Server uses the env-var PAT for every GG API call.
Browser-OAuth stdio (deprecated)	ENABLE_LOCAL_OAUTH=true (today's default in stdio)	Legacy uvx --from … flow that opens a localhost callback and stores the PAT on disk.

[!NOTE] Browser-driven OAuth in stdio mode is deprecated. New stdio deployments should authenticate with a PAT; OAuth-driven flows should use the hosted or self-hosted HTTP server. The stdio OAuth code path will be removed in a future release; until then it remains the default in stdio for backward compatibility.

Local stdio mode (PAT-only)

For CI/CD, airgapped environments, or older MCP clients, run the server locally over stdio with a PAT:

{
  "mcpServers": {
    "GitGuardian": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/GitGuardian/ggmcp.git",
        "gg-mcp-server"
      ],
      "env": {
        "ENABLE_LOCAL_OAUTH": "false",
        "GITGUARDIAN_PERSONAL_ACCESS_TOKEN": "your_pat_here",
        "GITGUARDIAN_URL": "https://dashboard.gitguardian.com"
      }
    }
  }
}

Create a PAT in your GitGuardian dashboard under API → Personal Access Tokens. The set of tools the server exposes depends on the PAT's scopes.

For Claude Desktop on macOS, the command field needs the absolute path to uvx (e.g. /Users/you/.local/bin/uvx) — Claude Desktop does not resolve $PATH for MCP servers.

Self-hosting the MCP server

The MCP server will be soon available out of the box as part of your GitGuardian self-hosted deployment (Helm chart). This section is only meant to describe how it works, but you don't have to set it up.

A Docker image is published at ghcr.io/gitguardian/mcp-server. Run it behind a reverse proxy that terminates TLS, then point your MCP clients at it. The container exposes the StreamableHTTP transport on port 8000 by default.

Minimum configuration:

docker run -p 8000:8000 \
  -e GITGUARDIAN_URL=https://dashboard.gitguardian.mycorp.local \
  -e IS_ON_PREM=true \
  -e MCP_BASE_URL=https://mcp.mycorp.local \
  -e MCP_OAUTH_PROXY_ENABLED=true \
  -e ENABLE_LOCAL_OAUTH=false \
  ghcr.io/gitguardian/mcp-server:latest \
  gunicorn --workers=4 --worker-class=uvicorn.workers.UvicornWorker \
           -b 0.0.0.0:8000 gg_mcp_server.http_app:app

IS_ON_PREM=true tells the server it talks to a self-hosted GIM instance (API served under /exposed/v1, self-hosted scope set). When unset, the server guesses from the GITGUARDIAN_URL hostname, which fails for self-hosted instances deployed under a gitguardian.com/gitguardian.tech domain — set it explicitly for any self-hosted deployment.

MCP_OAUTH_PROXY_ENABLED=true makes the server advertise itself as an OAuth Protected Resource (RFC 9728) and proxy /authorize, /token, /register to your GitGuardian dashboard. MCP clients then run the OAuth flow against your domain.

Configuration reference

Variable	Description	Default
GITGUARDIAN_URL	GitGuardian dashboard URL	https://dashboard.gitguardian.com
IS_ON_PREM	true => self-hosted; false => SaaS; unset ⇒ guess from hostname	Unset
GITGUARDIAN_PERSONAL_ACCESS_TOKEN	PAT (overrides OAuth)	Unset
GITGUARDIAN_SCOPES	Comma-separated OAuth scopes to request	Auto
GITGUARDIAN_CLIENT_ID	OAuth client ID	ggshield_oauth
GITGUARDIAN_TOKEN_NAME	Display name for OAuth-issued PATs	MCP Token
GITGUARDIAN_TOKEN_LIFETIME	PAT lifetime in days (or never)	30
MCP_PORT	Port for HTTP transport (unset ⇒ stdio)	Unset
MCP_HOST	Bind address for HTTP transport	127.0.0.1
MCP_BASE_URL	Public URL of this MCP server (OAuth proxy mode)	http://localhost:8000
MCP_OAUTH_PROXY_ENABLED	Advertise OAuth Protected Resource metadata	false
ENABLE_LOCAL_OAUTH	Legacy: enable stdio OAuth flow (deprecated)	true

Migration notes

The developer-mcp-server and secops-mcp-server console scripts are deprecated and re-export the unified gg-mcp-server. Update your MCP client configuration to invoke gg-mcp-server directly; both old scripts will be removed in a future release.

Want more?

Have a use case that isn't covered? Open an issue with your idea.

Development

See DEVELOPMENT.md for contributing, running tests, and adding new tools.