# GitHub MCP Server Comparison

## Overview

[GitHub's official MCP server](https://github.com/github/github-mcp-server) (30K stars, Go) exposes the GitHub API (repos, issues, PRs, code search, etc.) as MCP tools. It is a Go monolith with functional tool registration, group-based filtering, and dynamic tool descriptions that change based on context.

---

## How GitHub's MCP server works

1. **Functional tool registration**: Tools are defined via `toolsets.NewToolset()` with group-based filtering ("repos", "issues", "pull_requests", "code_search", etc.). Each toolset is a first-class object that can be enabled/disabled at startup.

2. **Dynamic tool descriptions**: Tool descriptions are context-aware — they change based on the current repository or organization context. This is a unique pattern not seen in other MCP servers.

3. **Go monolith**: A single binary with all tools compiled in. No HTTP proxy — tools execute in-process via the GitHub Go SDK (`go-github`). This is the Go equivalent of Stripe's in-process SDK pattern.

4. **Auth**: GitHub Personal Access Token (PAT) or GitHub App installation token. Supports fine-grained permissions via GitHub's existing token scoping.

5. **Transport**: stdio only (as of May 2026). No Streamable HTTP transport.

---

## How our system differs

| Aspect                   | GitHub MCP Server          | Coda MCP Server                        |
| ------------------------ | -------------------------- | -------------------------------------- |
| **Language**             | Go                         | TypeScript                             |
| **Execution**            | In-process (Go SDK)        | HTTP proxy to Express API              |
| **Tool registration**    | `toolsets.NewToolset()`    | Static `TOOL_DEFINITIONS` array        |
| **Tool gating**          | Group-based (`--toolsets`) | Domain filtering + exclusion set       |
| **Auth**                 | GitHub PAT / App token     | Bearer token forwarded to Express      |
| **Error handling**       | Go `error` returns         | `ToolCallOutcome` tagged union + hints |
| **Observability**        | Basic logging              | OTel tracing + metrics + MCP logging   |
| **Dynamic descriptions** | Yes (context-aware)        | No (static descriptions)               |
| **Concurrency**          | Go goroutines (implicit)   | Semaphore(5) explicit limiter          |

---

## What we are NOT adopting and why

1. **Dynamic tool descriptions**: Our tool descriptions are designed for AI comprehension and include business domain context. Making them dynamic based on current state would add complexity without clear benefit — the AI already receives state through tool results.

2. **Go monolith pattern**: Our existing Express API already handles auth, rate limiting, and tenant resolution. Rewriting tool handlers in Go would be a complete architecture change.

---

## What we are adopting

### 1. Group-based filtering pattern (partially adopted)

GitHub's `--toolsets` flag lets users enable specific tool groups. Our `CODA_MCP_DOMAINS` env var serves the same purpose. The pattern is validated by both implementations.

### 2. Functional toolset composition

GitHub's `toolsets.NewToolset()` is the Go equivalent of our composable `ToolPredicate` system in `tool-filter.ts`. Both decompose tool selection into composable units. This validates our approach.

---

## Validation of our approach

GitHub's MCP server validates two patterns we share:

1. **Domain-based tool grouping**: Both implementations organize tools into domains/groups and let users control which are exposed.
2. **Static analysis-friendly tool definitions**: Both implementations define tools as data (not decorators), enabling contract tests and catalog generation.

The key difference is GitHub's in-process execution vs. our HTTP proxy. GitHub can afford this because they own the API SDK. We proxy because our tools need the Express middleware stack.

---

## References

- [github/github-mcp-server](https://github.com/github/github-mcp-server) (GitHub)

---

_Comparison conducted 2026-05-10._