MCP Server

What it does

The MCP integration registers git-why mcp as a local stdio MCP server. Once registered, your coding agent has eight tools available:

Tool	Description
`gitwhy_status()`	Check setup state, pending commits, and sync status
`gitwhy_save(markdown, domain?, topic?)`	Save a context. Returns the context ID
`gitwhy_list(domain?, topic?)`	Browse saved contexts and the domain/topic tree
`gitwhy_search(query, repo?, domain?, limit?)`	Search contexts by keyword or natural language. Returns ranked results with snippets from local + cloud
`gitwhy_get(id)`	Retrieve a context by ID. Returns the full markdown
`gitwhy_sync(ids?, force?)`	Upload contexts to the cloud (private). Set `force=true` to bypass dedup checks
`gitwhy_publish(ids)`	Make contexts visible to team (shared)
`gitwhy_post_pr(ids?, pr_number?)`	Post context summary as a PR comment

Setup

Run git why setup and select MCP Server from the menu. GitWhy configures the MCP server automatically. To configure manually, add the following to your agent’s MCP config:

Run this in your terminal:

claude mcp add --transport stdio \
  -e GITWHY_API_KEY=YOUR_API_KEY \
  gitwhy -- git-why mcp

To install globally (all projects):

claude mcp add --transport stdio --scope user \
  -e GITWHY_API_KEY=YOUR_API_KEY \
  gitwhy -- git-why mcp

Verify it was added:

claude mcp list

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Or go to Settings → Cursor Settings → MCP → Add new global MCP server.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Or add via the MCPs icon in Cascade → Manage MCP Servers → View raw config.

Add to your Cline MCP settings file.CLI path: ~/.cline/data/settings/cline_mcp_settings.json VS Code: Click MCP Servers icon → Configure → Configure MCP Servers

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      },
      "disabled": false
    }
  }
}

Add to ~/.gemini/antigravity/mcp_config.json:Antigravity may start local MCP servers outside your project directory. Pin the repository explicitly:

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp", "--repo", "/path/to/your/project"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.gitwhy]
command = "git-why"
args = ["mcp"]

[mcp_servers.gitwhy.env]
GITWHY_API_KEY = "YOUR_API_KEY"

Add to Kilo Code’s VS Code extension settings (mcp_settings.json):

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Open the Kiro panel → click Open MCP Config, then add:

{
  "mcpServers": {
    "gitwhy": {
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "gitwhy": {
      "type": "local",
      "command": ["git-why", "mcp"],
      "environment": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      },
      "enabled": true
    }
  }
}

Go to your repository on GitHub → Settings → Copilot → Coding agent → MCP configuration, then paste:

{
  "mcpServers": {
    "gitwhy": {
      "type": "stdio",
      "command": "git-why",
      "args": ["mcp"],
      "env": {
        "GITWHY_API_KEY": "YOUR_API_KEY"
      },
      "tools": ["gitwhy_status", "gitwhy_save", "gitwhy_list", "gitwhy_search", "gitwhy_get", "gitwhy_sync", "gitwhy_publish", "gitwhy_post_pr"]
    }
  }
}

Copilot requires a tools array to allowlist which tools the agent can use.

Replace YOUR_API_KEY with the key from your GitWhy dashboard. You can also set GITWHY_API_KEY in your shell profile instead of the config file.

If you change the GITWHY_API_KEY in the config file, you must restart your coding agent for the change to take effect. The MCP server runs as a subprocess and inherits environment variables at startup — editing the config file does not update the running process.

How the agent uses MCP tools

Once configured, the agent calls GitWhy tools directly. You don’t need to tell it to use the CLI. Checking status:

You: "Are there any unsaved commits?"

Agent: [calls gitwhy_status()]
GitWhy: { pending_commits: 3, authenticated: true, ... }

Saving a context:

You: "Save this session with GitWhy."

Agent: [calls gitwhy_save(markdown="<context><title>Auth Middleware</title>...")]
GitWhy: ctx_a1b2c3d4

Browsing the context tree:

You: "What contexts exist in the authentication domain?"

Agent: [calls gitwhy_list(domain="authentication")]
GitWhy: [returns domain/topic tree with context summaries]

Searching (hybrid local + cloud):

You: "What did we decide about JWT tokens?"

Agent: [calls gitwhy_search(query="JWT tokens")]
GitWhy: [returns ranked results with title, snippet, score, files, and commit SHAs]

You: "Find all auth-related contexts in the backend domain."

Agent: [calls gitwhy_search(query="authentication", domain="backend")]
GitWhy: [returns filtered results from local contexts + cloud workspace contexts]

Search results include a relevance score, snippet, related files, and commit SHAs. The agent can call gitwhy_get on any result to read the full context. Retrieving a context:

You: "Get context ctx_a1b2c3d4."

Agent: [calls gitwhy_get(id="ctx_a1b2c3d4")]
GitWhy: [returns full markdown]

Syncing and sharing:

You: "Sync my contexts to the cloud and share them with the team."

Agent: [calls gitwhy_sync()]
Agent: [calls gitwhy_publish(ids='["ctx_a1b2c3d4"]')]
GitWhy: [contexts uploaded and shared]

Posting to a PR:

You: "Post the context to the PR."

Agent: [calls gitwhy_post_pr()]
GitWhy: [context summary posted as PR comment]

Verify the server is running

git why mcp --ping

Expected output:

GitWhy MCP server ready. Tools: gitwhy_status, gitwhy_save, gitwhy_list, gitwhy_search, gitwhy_get, gitwhy_sync, gitwhy_publish, gitwhy_post_pr

Getting Started

Core Features

Sharing & Collaboration

Interfaces

Integration Guide

CLI Reference

Context Format

Plans & Pricing

What it does

Setup

How the agent uses MCP tools

Verify the server is running

See also

​What it does

​Setup

​How the agent uses MCP tools

​Verify the server is running

​See also

What it does

Setup

How the agent uses MCP tools

Verify the server is running

See also