GitHub App

Summary

Full-surface MCP integration with the GitHub REST API and GraphQL API, authenticated as a GitHub App installation rather than a user. Lets a Prospector Studio agent walk and act on the repositories the App is installed on: list repos, manage issues and comments, list pull requests, manage labels, walk sub-issue hierarchies, and operate Projects v2 boards (items, fields, statuses).

The host owns the auth flow: it signs an RS256 JWT with the App's PEM private key (10-minute lifetime, iss = App ID), exchanges the JWT for an installation access token at POST /app/installations/{id}/access_tokens, and injects that token as the Authorization: Bearer … egress header. Refresh is automatic — installation tokens last one hour, and the host re-mints on expiry.

This plugin is read-write. It creates issues and comments, updates issues, mutates labels, adds and removes sub-issues, and adds/removes/updates Projects v2 items. Bind it to agents only when that level of authority is intended.

Capabilities

• Repositories — list repos accessible to the installation; list org repos; get repo details.
• Issues — list, get, create, update; list comments; add comments.
• Pull requests — list and get (read-only surface).
• Labels — list repo labels; add and remove labels via GraphQL (node IDs).
• Sub-issues — add and remove parent ↔ child relationships.
• Projects v2 — list org projects; get a project, its views, fields, and items; get a single item by ID; add and remove project items; update project item field values (status, dates, numbers, text).
• GraphQL get_issue_detail — fetch an issue together with its sub-issues, parent, labels, assignees, and project items in a single round trip.

Required Headers

Credential Permissions

GitHub App permissions are declared on the App itself (in the App's settings under Permissions & events) and granted at installation time to a specific repository scope (all repos in an org, or a selected list). The installation access token the host mints inherits exactly those declared permissions, intersected with the installations's repository selection — there is no per-token scope; the App's manifest is the contract.

Permissions are organized by resource (Issues, Pull requests, Contents, Metadata, Pages, Projects, Single file, etc.) and graded as Read, Read & write, or No access. For agent use, declare only the permissions the bound tools actually need. The minimum permission set for this plugin's tool surface is:

• Repository permissions → Metadata: Read (always required; gates list_repos, get_repo, list_org_repos).
• Issues: Read & write for issue CRUD, comments, sub-issues, and label changes on issues.
• Pull requests: Read for list_pulls, get_pull. Bump to Read & write if you later add PR mutation tools.
• Organization permissions → Projects: Read & write for the Projects v2 tools. Use Projects: Read if you only need to read boards.

For read-only agent behavior, set every permission to Read (Issues: Read, Pull requests: Read, Projects: Read) and skip the write-flavored tools when binding to the agent. Reduce blast radius further by installing the App on a curated repo list rather than "all repositories" — installation scope is enforced server-side and cannot be bypassed by the token.

References: Choosing permissions for a GitHub App · Authenticating as a GitHub App installation.

Allowed Hosts

api.github.com

Tools

The plugin advertises 27 MCP tools, organized by capability domain. The REST tools call GitHub's REST API (/repos/..., /orgs/...); the Projects v2, label-by-node-id, sub-issue, and get_issue_detail tools call GraphQL (POST /graphql).

Repositories

Issues & Comments

Pull Requests

Labels & Sub-Issues

Projects v2

Invocation Examples

Create an issue:

{
  "name": "create_issue",
  "arguments": {
    "owner": "strike48",
    "repo": "construct",
    "title": "Construct: clarify failure mode for stale tool discovery",
    "body": "When the Atlassian MCP gateway is unreachable at refresh time, document what agents see.",
    "labels": ["docs"]
  }
}

Move a project item to a new status (single-select field):

{
  "name": "update_project_item_field",
  "arguments": {
    "projectId": "PVT_kwDOABcdEf4ABCDE",
    "itemId":    "PVTI_lADOABcdEf4ABCDEzgABCDEF",
    "fieldId":   "PVTSSF_lADOABcdEf4ABCDEzgABCDxx",
    "value":     {"singleSelectOptionId": "f75ad846"}
  }
}

Operational Notes

• No user identity. Installation tokens act as the App, not as any user. /user returns 403 Resource not accessible by integration and is intentionally not exposed. App-level endpoints (/app, /app/installations) require a JWT, not an installation token, and are also out of scope.
• REST node_id ↔ GraphQL. GraphQL mutations (add_labels, remove_labels, add_sub_issue, project tools) take node IDs, not numeric IDs or names. Most REST list/get responses include a node_id field — use it directly. For labels, call list_labels and pull node_id; for issues, call get_issue and pull node_id; for projects, walk list_org_projects → get_project → get_project_items to get the IDs you need.
• GraphQL field-value shape. update_project_item_field accepts a polymorphic value object: {"singleSelectOptionId": "..."} for status / single-select, {"number": 1} for number fields, {"date": "2024-01-15"} for date fields, {"text": "..."} for text fields. The shape must match the field's dataType from get_project_fields.
• Pagination. REST endpoints take page (1-indexed) and per_page (max 100). GraphQL endpoints take first (max 100) and after (cursor from pageInfo.endCursor).
• Rate limits. GitHub App installation tokens have a higher REST rate limit ceiling than personal tokens (5,000 req/hr scaled by repo count, capped at 12,500/hr). GraphQL is point-cost-based — each request consumes points proportional to the data fetched. The plugin does not rate-limit on its own; pace agent calls accordingly.
• Reference docs. GitHub REST API reference · GitHub GraphQL API reference · GitHub App permissions.