feat: add GitHub MCP server integration by lklimek · Pull Request #10 · lklimek/claudius

lklimek · 2026-03-10T14:44:05Z

Summary

Integrate GitHub MCP server (remote HTTP) for all agents via https://api.githubcopilot.com/mcp/
Auth centralized in .mcp.json using GH_TOKEN (preferred) or GITHUB_TOKEN (fallback) — no auth duplication in agent frontmatter
All agents inherit readonly GitHub MCP from plugin-level config; only claudius gets inline read-write override with scoped toolsets
Demote ghsudo from primary to optional fallback — scripts try gh directly, fall back to ghsudo on 403/404
README: setup guide with fine-grained PAT permissions table and creation link

What changed?

File	Change
`.claude-plugin/.mcp.json`	New — centralized GitHub MCP config (auth + all toolsets + readonly)
`.claude-plugin/plugin.json`	Version bump `1.13.2` → `1.14.0`
`agents/claudius.md`	Inline GitHub MCP override (read-write, scoped toolsets)
`scripts/gh-*.sh` (3 files)	`run_gh()` helper — try direct, ghsudo fallback on 403/404
`skills/git-and-github/SKILL.md`	ghsudo demoted to optional fallback
`README.md`	GitHub MCP setup section + ghsudo reframed as optional
`CHANGELOG.md`	v1.14.0 entry

Test plan

Install plugin, run /mcp — github server appears connected
Spawn a non-claudius agent — verify it has readonly GitHub MCP access
Spawn claudius agent — verify it has read-write GitHub MCP access
Run gh-post-review.sh without ghsudo installed — verify direct gh call works
Run gh-post-review.sh with read-only token — verify ghsudo fallback triggers

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

Integrate the remote GitHub MCP server (api.githubcopilot.com/mcp/) for all agents. Auth is centralized in .mcp.json using GH_TOKEN/GITHUB_TOKEN — no auth duplication in agent frontmatter. All agents inherit readonly config from plugin level; only claudius gets an inline read-write override. Also demotes ghsudo from primary to optional fallback — scripts now try gh directly first, falling back to ghsudo on 403/404 permission errors. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a centralized GitHub MCP server configuration to the Claude plugin so agents can access GitHub APIs via a shared remote HTTP MCP endpoint, while updating docs and helper scripts to treat ghsudo as an optional fallback.

Changes:

Add plugin-level GitHub MCP config (.claude-plugin/.mcp.json) using GH_TOKEN/GITHUB_TOKEN, with readonly + toolset headers.
Update claudius agent to override GitHub MCP settings for scoped (intended read-write) access.
Update GitHub helper scripts and docs to try gh first and only fall back to ghsudo on 403/404.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`.claude-plugin/.mcp.json`	Introduces centralized GitHub MCP server config (HTTP endpoint + headers).
`.claude-plugin/plugin.json`	Version bump to 1.14.0.
`agents/claudius.md`	Adds an inline GitHub MCP server override for `claudius`.
`scripts/gh-post-review.sh`	Adds `run_gh()` wrapper to use `gh` with `ghsudo` fallback.
`scripts/gh-request-reviewer.sh`	Adds `run_gh()` wrapper to use `gh` with `ghsudo` fallback.
`scripts/gh-resolve-review-threads.sh`	Adds `run_gh()` wrapper and switches mutation call from `ghsudo` to wrapper.
`skills/git-and-github/SKILL.md`	Reframes `ghsudo` as optional fallback; updates push guidance.
`README.md`	Documents GitHub MCP setup and reframes `ghsudo` as optional.
`CHANGELOG.md`	Adds 1.14.0 entry describing MCP + ghsudo behavior changes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T15:19:48Z

@@ -29,4 +40,4 @@ for id in "$@"; do
 done


With set -euo pipefail, ((i++)) returns exit status 1 on the first iteration (because the expression evaluates to 0), which can cause the script to exit before building the full GraphQL mutation. Use a form that always returns success under -e (e.g., pre-increment) or otherwise guard the arithmetic command.

Copilot · 2026-03-10T15:19:49Z

+Each agent gets only the toolsets it needs (via `X-MCP-Toolsets` header) to minimize context size. All agents except `claudius` run in read-only mode — writes go through `gh` CLI.
+
+**Step 1 — Create a fine-grained PAT:**
+
+[→ Create a new fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+
+Set the token expiration and repository access scope as needed, then grant these **repository permissions**:
+
+| Permission | Access | Used for |
+|---|---|---|
+| **Actions** | Read-only | View workflow runs and logs |
+| **Contents** | Read and write | Read code, push to branches |
+| **Discussions** | Read-only | Read repository discussions |
+| **Issues** | Read and write | Create issues, add comments |
+| **Metadata** | Read-only | Basic repository metadata (always required) |
+| **Pull requests** | Read and write | Create PRs, review, comment, resolve threads |
+
+> **Tip:** The GitHub MCP server auto-detects your token's permissions and hides tools you don't have access to. Start with the permissions above and add more if needed.
+


The PAT permission table asks for several read/write scopes (e.g., Contents/Issues/Pull requests), but the text above says most agents run in read-only mode. To keep least-privilege guidance consistent, consider documenting a minimal read-only permission set (and separately call out when/why write permissions are needed, e.g. only for claudius read-write MCP usage).

Suggested change

Each agent gets only the toolsets it needs (via `X-MCP-Toolsets` header) to minimize context size. All agents except `claudius` run in read-only mode — writes go through `gh` CLI.

**Step 1 — Create a fine-grained PAT:**

[→ Create a new fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new)

Set the token expiration and repository access scope as needed, then grant these **repository permissions**:

| Permission | Access | Used for |

|---|---|---|

| **Actions** | Read-only | View workflow runs and logs |

| **Contents** | Read and write | Read code, push to branches |

| **Discussions** | Read-only | Read repository discussions |

| **Issues** | Read and write | Create issues, add comments |

| **Metadata** | Read-only | Basic repository metadata (always required) |

| **Pull requests** | Read and write | Create PRs, review, comment, resolve threads |

> **Tip:** The GitHub MCP server auto-detects your token's permissions and hides tools you don't have access to. Start with the permissions above and add more if needed.

Each agent gets only the toolsets it needs (via `X-MCP-Toolsets` header) to minimize context size. All agents except `claudius` use MCP in read-only mode — repository writes are done by you (e.g. via `git`/`gh`) or, if you explicitly enable it, by `claudius` using write-capable tools.

**Step 1 — Create a fine-grained PAT:**

[→ Create a new fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new)

Set the token expiration and repository access scope as needed, then grant at least these **read-only repository permissions** (recommended baseline):

| Permission | Access | Used for |

|---|---|---|

| **Actions** | Read-only | View workflow runs and logs |

| **Contents** | Read-only | Read code and repository files |

| **Discussions** | Read-only | Read repository discussions |

| **Issues** | Read-only | View issues and existing comments |

| **Metadata** | Read-only | Basic repository metadata (always required) |

| **Pull requests** | Read-only | View PRs, reviews, comments, and statuses |

For most workflows (read-only agents, manual `git`/`gh` usage), the permissions above are sufficient and follow least privilege.

If you want `claudius` (or other agents) to create or modify GitHub resources via MCP (e.g. open PRs, file issues, push commits), also grant these **optional write permissions**:

| Permission | Access | Used for |

|---|---|---|

| **Contents** | Read and write | Push commits, create/update branches, edit files via API |

| **Issues** | Read and write | Create issues, edit titles/descriptions, add comments |

| **Pull requests** | Read and write | Open PRs, update descriptions, comment, resolve threads |

> **Tip:** The GitHub MCP server auto-detects your token's permissions and hides tools you don't have access to. Start with the minimal read-only set above and add the optional write permissions only if you need automation.

Copilot · 2026-03-10T15:19:49Z

+- GitHub MCP server (remote HTTP) via `https://api.githubcopilot.com/mcp/` — centralized in `.mcp.json`
+- All agents inherit GitHub MCP from plugin-level config (readonly, all toolsets)
+- `claudius` gets inline read-write override with scoped toolsets
+- PAT auth via `GH_TOKEN` (preferred) or `GITHUB_TOKEN` (fallback) — no auth duplication in agent frontmatter
+- README setup guide with fine-grained PAT permissions table


This changelog bullet says auth is centralized with “no auth duplication in agent frontmatter”, but agents/claudius.md now includes an inline Authorization header for the GitHub MCP server. Either adjust the changelog wording to reflect the exception, or rework the claudius override so auth truly remains centralized.

Copilot · 2026-03-10T15:19:49Z

+    type: http
+    url: "https://api.githubcopilot.com/mcp/"
+    headers:
+      Authorization: "Bearer ${GH_TOKEN:-${GITHUB_TOKEN}}"


claudius now duplicates the GitHub MCP Authorization header inline, which conflicts with the stated goal of centralizing auth in .claude-plugin/.mcp.json and creates drift risk if the auth mechanism changes. If the config format allows it, prefer inheriting the centralized auth and only overriding the toolsets/read-write behavior here; otherwise, please document why this one agent must duplicate auth.

Suggested change

Authorization: "Bearer ${GH_TOKEN:-${GITHUB_TOKEN}}"

Copilot · 2026-03-10T15:19:49Z

+run_gh() {
+  if output=$(gh "$@" 2>&1); then
+    echo "$output"
+  elif command -v ghsudo >/dev/null 2>&1 && echo "$output" | grep -qiE '403|404|Resource not accessible'; then
+    ghsudo gh "$@"
+  else


In run_gh(), output is implicitly a global variable. Declaring it as a local variable inside the function avoids accidental clashes if the script grows (and is safer under set -u).

- Remove X-MCP-Readonly from .mcp.json (PAT permissions are the real ACL) - Simplify claudius.md mcpServers to name references only - README: pre-fill PAT creation link with correct permissions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add "Agent Reuse" subsection under Spawning: prefer SendMessage to running agents over spawning fresh ones for follow-up work in the same scope. Add corresponding anti-pattern #10 to reinforce the pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

) * feat(skills): extract grand-admiral orchestration skill from claudius agent Move ~150 lines of multi-agent orchestration doctrine (spawning, worktree isolation, team coordination, scaling, recovery, anti-patterns) plus planning, crew roster, skills reference, and programme management patterns into a dedicated `grand-admiral` skill. The claudius agent prompt drops from 206 to 55 lines — personality + session protocol only — improving resilience to context compaction. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor(agents): move session protocol, docs, attribution to grand-admiral skill Further slim the claudius agent to personality + role/focus only (30 lines). Session protocol (Always section), documentation conventions, and attribution rules now live in the grand-admiral skill alongside all other orchestration knowledge. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(grand-admiral): add agent reuse pattern and anti-pattern #10 Add "Agent Reuse" subsection under Spawning: prefer SendMessage to running agents over spawning fresh ones for follow-up work in the same scope. Add corresponding anti-pattern #10 to reinforce the pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(grand-admiral): clarify Bilby vs Marvin adversarial split Update Crew Roster roles to make the builder/breaker contract explicit: Bilby builds and fixes code, Marvin proves code wrong and never fixes. Add explanatory note after the roster table with the fix-routing pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(grand-admiral,agents): formalize candy economy incentive system Add dedicated "Candy Economy" section to grand-admiral skill with per-agent candy rules: Marvin earns for confirmed bugs, Bilby earns for false positives, all others earn for confirmed findings in their domain. Coordinator validates all awards. Add Mindset sections to Bilby, Nagatha, Trillian, and Diziet agents with candy motivation. Marvin, Smythe, and Adams already had candy mindset — no changes needed. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: strengthen MemCan context injection in grand-admiral skill - Expand one-liner into concrete 5-step procedure with score threshold - Add Prior Knowledge prompt template for agent context injection - Add prior knowledge to Agent Prompt Requirements checklist Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: review improvements --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

lklimek marked this pull request as ready for review March 10, 2026 15:12

lklimek requested a review from Copilot March 10, 2026 15:12

Copilot started reviewing on behalf of lklimek March 10, 2026 15:12 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

lklimek merged commit fddf09b into main Mar 10, 2026

lklimek deleted the feat/github-mcp-server branch March 10, 2026 15:24

lklimek mentioned this pull request Apr 8, 2026

feat: extract grand-admiral skill, candy economy, adversarial roles #30

Merged

7 tasks

lklimek mentioned this pull request Jun 12, 2026

feat(bug-investigation): root-cause discipline skill + wiring (4.10.0) #49

Merged

Navigation Menu

feat: add GitHub MCP server integration - #10

feat: add GitHub MCP server integration#10
lklimek merged 2 commits into
mainfrom
feat/github-mcp-server

lklimek commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lklimek commented Mar 10, 2026

Summary

What changed?

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants