ContextQMD
Back to Github Mcp Server

Feature Flags

docs/feature-flags.md

1.12.024.8 KB
Original Source

Feature Flags

Feature flags let you opt into experimental tool behavior on top of the default GitHub MCP Server surface. Insiders Mode turns on a curated subset of these flags automatically — see Insiders Features for that specific set.

For background on how flags resolve at request time, see the resolution section in the Insiders docs.

Enabling a flag

MethodRemote ServerLocal Server
HeaderX-MCP-Features: <flag>,<flag>N/A
URL query parameter?features=<flag>,<flag> on the server URLN/A
CLI flagN/A--features=<flag>,<flag>
Environment variableN/AGITHUB_FEATURES=<flag>,<flag>

The URL query parameter exists for clients that compose the server URL on the user's behalf (hosted IDEs, agent platforms) and cannot set custom headers. When both the query parameter and the header are present, the header wins — even when its value is empty, whitespace-only, or contains only unknown flags. The two channels are never combined.

The complete query string is preserved during OAuth protected-resource metadata discovery because it is part of the canonical resource identifier. Query parameters also participate in HTTP cache keys, while MCP responses vary on X-MCP-Features so a header override cannot reuse a response selected for a different feature set. Feature names are configuration identifiers, not secrets; as with any URL query value, they may appear in client history, proxy logs, and server access logs.

Only flags listed in AllowedFeatureFlags can be enabled by end users. Insiders-only flags are not user-toggleable.

Declaring tool availability

Tools, resources, and prompts use inventory.NewFeatureRule when feature flags change whether they are available. Each rule declares the flags it references and evaluates them with a fail-closed FeatureResolver, so normal Go boolean expressions can represent AND, OR, NOT, and mixed conditions:

go
tool.FeatureRule = inventory.NewFeatureRule(
	[]inventory.FeatureFlag{x, y},
	func(featureAsBool inventory.FeatureResolver) bool {
		return !(featureAsBool(x) && featureAsBool(y))
	},
)

Library consumers migrating existing inventory declarations should replace FeatureFlagEnable, FeatureFlagEnableAll, and FeatureFlagDisable on ServerTool, ServerResourceTemplate, and ServerPrompt with FeatureRule. FeatureFlagChecker and ToolDependencies.IsFeatureEnabled continue to accept string flag names.

Rules are evaluated lazily after request narrowing and static availability filters. Normal Go short-circuiting avoids checks that cannot affect the result, while one request-owned memo ensures each flag actually reached is resolved at most once across tools, resources, prompts, and deps.IsFeatureEnabled. Unavailable named tool calls skip rule evaluation but remain registered so the handler can return the specific client-availability error.

Feature predicates are pure and may depend only on their resolver. Construction validates every combination of up to 16 declared flags, so an undeclared lookup fails immediately even when ordinary evaluation would short-circuit that branch.

The inventory's string-based checker owns request feature state. Once installed, that state is authoritative; a checker stored on tool dependencies is used only as a fallback when handlers are invoked directly without request state. Feature checkers must not call ResolveFeature; nested resolution fails the owning check closed.

Tools affected by each flag

The list below is regenerated by comparing the default tool surface with each user-controllable flag enabled individually. Complex multi-flag rules may require separate documentation. Flags that only affect runtime behavior (such as output formatting) won't appear here.

<!-- START AUTOMATED FEATURE FLAG TOOLS -->

remote_mcp_ui_apps

  • create_pull_request - Open new pull request

    • OAuth Challenge Scopes: repo
    • MCP App UI: ui://github-mcp-server/pr-write
    • base: Branch to merge into (string, required)
    • body: PR description (string, optional)
    • draft: Create as draft PR (boolean, optional)
    • head: Branch containing changes (string, required)
    • maintainer_can_modify: Allow maintainer edits (boolean, optional)
    • owner: Repository owner (string, required)
    • repo: Repository name (string, required)
    • reviewers: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], optional)
    • title: PR title (string, required)

  • get_me - Get my user profile

    • MCP App UI: ui://github-mcp-server/get-me
    • No parameters required

  • issue_write - Create or update issue/pull request

    • OAuth Challenge Scopes: repo
    • MCP App UI: ui://github-mcp-server/issue-write
    • assignees: Usernames to assign to this issue (string[], optional)
    • body: Issue body content (string, optional)
    • duplicate_of: Issue number that this issue is a duplicate of. Required when state_reason is 'duplicate'. (number, optional)
    • issue_fields: Issue field values to set or clear. Each item requires 'field_name' and exactly one of 'value', 'field_option_name', or 'delete: true'. (object[], optional)
    • issue_number: Issue number to update (number, optional)
    • labels: Labels to apply to this issue (string[], optional)
    • method: Write operation to perform on a single issue. Options are:
      • 'create' - creates a new issue.
      • 'update' - updates an existing issue. (string, required)
    • milestone: Milestone number (number, optional)
    • owner: Repository owner (string, required)
    • parent_issue_number: Issue number of the parent issue. Only used when method is 'create' and cannot be combined with issue_fields. The new issue is created and attached to this parent in the same operation. (number, optional)
    • parent_owner: Repository owner of the parent issue. Must be provided with parent_repo. Omit both to use owner and repo. Only used when method is 'create' and parent_issue_number is provided. (string, optional)
    • parent_repo: Repository name of the parent issue. Must be provided with parent_owner. Omit both to use owner and repo. Only used when method is 'create' and parent_issue_number is provided. (string, optional)
    • repo: Repository name (string, required)
    • state: New state (string, optional)
    • state_reason: Reason for the state change. Ignored unless state is changed. (string, optional)
    • title: Issue title (string, optional)
    • type: Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner organization. If the repository doesn't support issue types, omit this parameter. (string | null, optional)

  • ui_get - Get UI data

    • OAuth Challenge Scopes: repo, read:org
    • method: The type of data to fetch (string, required)
    • owner: Repository owner (required for all methods) (string, required)
    • repo: Repository name (required for labels, assignees, milestones, branches, issue fields, reviewers) (string, optional)

  • update_pull_request - Edit pull request

    • OAuth Challenge Scopes: repo
    • MCP App UI: ui://github-mcp-server/pr-edit
    • base: New base branch name (string, optional)
    • body: New description (string, optional)
    • draft: Mark pull request as draft (true) or ready for review (false) (boolean, optional)
    • maintainer_can_modify: Allow maintainer edits (boolean, optional)
    • owner: Repository owner (string, required)
    • pullNumber: Pull request number to update (number, required)
    • repo: Repository name (string, required)
    • reviewers: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], optional)
    • state: New state (string, optional)
    • title: New title (string, optional)

issues_granular

  • add_issue_comment_reaction - Add Reaction to Issue or Pull Request Comment

    • OAuth Challenge Scopes: repo
    • comment_id: The issue or pull request comment ID (number, required)
    • content: The emoji reaction type (string, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • add_issue_reaction - Add Reaction to Issue or Pull Request

    • OAuth Challenge Scopes: repo
    • content: The emoji reaction type (string, required)
    • issue_number: The issue number (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • add_sub_issue - Add Sub-Issue

    • OAuth Challenge Scopes: repo
    • issue_number: The parent issue number (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • replace_parent: If true, reparent the sub-issue if it already has a parent (boolean, optional)
    • repo: Repository name (string, required)
    • sub_issue_id: The ID of the sub-issue to add. ID is not the same as issue number (number, required)

  • create_issue - Create Issue

    • OAuth Challenge Scopes: repo
    • body: Issue body content (optional) (string, optional)
    • owner: Repository owner (username or organization) (string, required)
    • parent_issue_number: Issue number of the parent issue. The new issue is created and attached to this parent in the same operation. (number, optional)
    • parent_owner: Repository owner of the parent issue. Must be provided with parent_repo. Omit both to use owner and repo. Only used when parent_issue_number is provided. (string, optional)
    • parent_repo: Repository name of the parent issue. Must be provided with parent_owner. Omit both to use owner and repo. Only used when parent_issue_number is provided. (string, optional)
    • repo: Repository name (string, required)
    • title: Issue title (string, required)

  • remove_sub_issue - Remove Sub-Issue

    • OAuth Challenge Scopes: repo
    • issue_number: The parent issue number (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)
    • sub_issue_id: The ID of the sub-issue to remove. ID is not the same as issue number (number, required)

  • reprioritize_sub_issue - Reprioritize Sub-Issue

    • OAuth Challenge Scopes: repo
    • after_id: The ID of the sub-issue to place this after (either after_id OR before_id should be specified) (number, optional)
    • before_id: The ID of the sub-issue to place this before (either after_id OR before_id should be specified) (number, optional)
    • issue_number: The parent issue number (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)
    • sub_issue_id: The ID of the sub-issue to reorder. ID is not the same as issue number (number, required)

  • set_issue_fields - Set Issue Fields

    • OAuth Challenge Scopes: repo
    • fields: Array of issue field values to set. Each element must have a 'field_id' (string, the GraphQL node ID of the field) and exactly one value field: 'text_value' for text fields, 'number_value' for number fields, 'date_value' (ISO 8601 date string) for date fields, or 'single_select_option_id' (the GraphQL node ID of the option) for single select fields. Set 'delete' to true to remove a field value. (object[], required)
    • issue_number: The issue number to update (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • update_issue_assignees - Update Issue Assignees

    • OAuth Challenge Scopes: repo
    • assignees: GitHub usernames to assign to this issue. ([], required)
    • issue_number: The issue number to update (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • update_issue_body - Update Issue Body

    • OAuth Challenge Scopes: repo
    • body: The new body content for the issue (string, required)
    • issue_number: The issue number to update (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • update_issue_labels - Update Issue Labels

    • OAuth Challenge Scopes: repo
    • issue_number: The issue number to update (number, required)
    • labels: Labels to apply to this issue. ([], required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • update_issue_milestone - Update Issue Milestone

    • OAuth Challenge Scopes: repo
    • issue_number: The issue number to update (number, required)
    • milestone: The milestone number to set on the issue (integer, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • update_issue_state - Update Issue State

    • OAuth Challenge Scopes: repo
    • confidence: How confident you are in this choice. Use 'HIGH' for clear signal or explicit user request, 'MEDIUM' for reasonable inference with some ambiguity, 'LOW' for best guess with limited signal. (string, optional)
    • duplicate_of: The issue number of the canonical issue this issue duplicates. Only valid when state_reason is 'duplicate'. Required when is_suggestion is true and state_reason is 'duplicate'. The issue number is resolved to a database ID before being sent to the API. (number, optional)
    • is_suggestion: If true, this state change is sent to the API as a suggestion (suggest:true) rather than an applied change. Whether the change is applied or recorded as a proposal is determined by the API. (boolean, optional)
    • issue_number: The issue number to update (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • rationale: One concise sentence explaining what specifically about the issue led you to choose this state. State the concrete signal (e.g. 'The reported crash is fixed in v2.1' → completed). (string, optional)
    • repo: Repository name (string, required)
    • state: The new state for the issue (string, required)
    • state_reason: The reason for the state change (only for closed state) (string, optional)

  • update_issue_title - Update Issue Title

    • OAuth Challenge Scopes: repo
    • issue_number: The issue number to update (number, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)
    • title: The new title for the issue (string, required)

  • update_issue_type - Update Issue Type

    • OAuth Challenge Scopes: repo
    • confidence: How confident you are in this choice. Use 'HIGH' for clear signal or explicit user request, 'MEDIUM' for reasonable inference with some ambiguity, 'LOW' for best guess with limited signal. (string, optional)
    • is_suggestion: If true, this issue type change is sent to the API as a suggestion (suggest:true) rather than an applied value. Whether the type is applied or recorded as a proposal is determined by the API. (boolean, optional)
    • issue_number: The issue number to update (number, required)
    • issue_type: The issue type to set, or null to remove the current type (string | null, required)
    • owner: Repository owner (username or organization) (string, required)
    • rationale: One concise sentence explaining what specifically about the issue led you to choose this type. State the concrete signal (e.g. 'Reports a crash when saving' → bug, 'Asks for dark mode support' → feature). (string, optional)
    • repo: Repository name (string, required)

pull_requests_granular

  • add_pull_request_review_comment - Add Pull Request Review Comment

    • OAuth Challenge Scopes: repo
    • body: The comment body (string, required)
    • line: The line number in the diff to comment on (optional) (number, optional)
    • owner: Repository owner (username or organization) (string, required)
    • path: The relative path of the file to comment on (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)
    • side: The side of the diff to comment on (optional) (string, optional)
    • startLine: The start line of a multi-line comment (optional) (number, optional)
    • startSide: The start side of a multi-line comment (optional) (string, optional)
    • subjectType: The subject type of the comment (string, required)

  • add_pull_request_review_comment_reaction - Add Pull Request Review Comment Reaction

    • OAuth Challenge Scopes: repo
    • comment_id: The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...). (number, required)
    • content: The emoji reaction type (string, required)
    • owner: Repository owner (username or organization) (string, required)
    • repo: Repository name (string, required)

  • create_pull_request_review - Create Pull Request Review

    • OAuth Challenge Scopes: repo
    • body: The review body text (optional) (string, optional)
    • commitID: The SHA of the commit to review (optional, defaults to latest) (string, optional)
    • event: The review action to perform. If omitted, creates a pending review. (string, optional)
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)

  • delete_pending_pull_request_review - Delete Pending Pull Request Review

    • OAuth Challenge Scopes: repo
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)

  • request_pull_request_reviewers - Request Pull Request Reviewers

    • OAuth Challenge Scopes: repo
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)
    • reviewers: GitHub usernames or ORG/team-slug team reviewers to request reviews from (string[], required)

  • resolve_review_thread - Resolve Review Thread

    • OAuth Challenge Scopes: repo
    • threadID: The node ID of the review thread to resolve (e.g., PRRT_kwDOxxx) (string, required)

  • submit_pending_pull_request_review - Submit Pending Pull Request Review

    • OAuth Challenge Scopes: repo
    • body: The review body text (optional) (string, optional)
    • event: The review action to perform (string, required)
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)

  • unresolve_review_thread - Unresolve Review Thread

    • OAuth Challenge Scopes: repo
    • threadID: The node ID of the review thread to unresolve (e.g., PRRT_kwDOxxx) (string, required)

  • update_pull_request_body - Update Pull Request Body

    • OAuth Challenge Scopes: repo
    • body: The new body content for the pull request (string, required)
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)

  • update_pull_request_draft_state - Update Pull Request Draft State

    • OAuth Challenge Scopes: repo
    • draft: Set to true to convert to draft, false to mark as ready for review (boolean, required)
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)

  • update_pull_request_state - Update Pull Request State

    • OAuth Challenge Scopes: repo
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)
    • state: The new state for the pull request (string, required)

  • update_pull_request_title - Update Pull Request Title

    • OAuth Challenge Scopes: repo
    • owner: Repository owner (username or organization) (string, required)
    • pullNumber: The pull request number (number, required)
    • repo: Repository name (string, required)
    • title: The new title for the pull request (string, required)

file_blame

  • get_file_blame - Get file blame information
    • OAuth Challenge Scopes: repo
    • after: Cursor for pagination. Use the cursor from the previous response. (string, optional)
    • end_line: Optional 1-based ending line of the window of interest. Must be >= start_line when both are provided. (number, optional)
    • owner: Repository owner (username or organization) (string, required)
    • path: Path to the file in the repository, relative to the repository root (string, required)
    • perPage: Results per page for pagination (min 1, max 100) (number, optional)
    • ref: Git reference (branch, tag, or commit SHA). Defaults to the repository's default branch (HEAD). (string, optional)
    • repo: Repository name (string, required)
    • start_line: Optional 1-based starting line of the window of interest. Only ranges overlapping [start_line, end_line] are returned, clamped to the window. (number, optional)

issue_dependencies

  • issue_dependency_read - Read issue dependencies

    • OAuth Challenge Scopes: repo
    • issue_number: The number of the issue (number, required)
    • method: The read operation to perform on a single issue's dependencies. Options are:
      1. get_blocked_by - List the issues that block this issue (this issue is blocked by them).
      2. get_blocking - List the issues that this issue blocks. (string, required)
    • owner: The owner of the repository (string, required)
    • page: Page number for pagination (min 1) (number, optional)
    • perPage: Results per page for pagination (min 1, max 100) (number, optional)
    • repo: The name of the repository (string, required)

  • issue_dependency_write - Change issue dependency

    • OAuth Challenge Scopes: repo
    • issue_number: The number of the subject issue (number, required)
    • method: The action to perform. Options are:
      • 'add' - create the dependency relationship.
      • 'remove' - delete the dependency relationship. (string, required)
    • owner: The owner of the subject issue's repository (string, required)
    • related_issue_number: The number of the related issue to link or unlink (number, required)
    • related_owner: The owner of the related issue's repository. Defaults to 'owner' when omitted. (string, optional)
    • related_repo: The name of the related issue's repository. Defaults to 'repo' when omitted. (string, optional)
    • repo: The name of the subject issue's repository (string, required)
    • type: The relationship direction relative to the subject issue. Options are:
      • 'blocked_by' - the subject issue is blocked by the related issue.
      • 'blocking' - the subject issue blocks the related issue. (string, required)

duplicate_detection

  • find_duplicate - Find duplicate issues
    • OAuth Challenge Scopes: repo
    • confidence_threshold: Minimum similarity threshold a candidate must meet to be returned; higher values are stricter. When omitted, the API's high-precision default is used. The scale is defined by the API, so no client-side bounds are enforced. (number, optional)
    • issue_number: The number of the existing issue to find duplicates for (number, required)
    • owner: The owner of the repository (string, required)
    • page: Page number for pagination (min 1) (number, optional)
    • perPage: Results per page for pagination (min 1, max 100) (number, optional)
    • repo: The name of the repository (string, required)

thread_resolution_reason

  • pull_request_review_write - Write operations (create, submit, delete) on pull request reviews
    • OAuth Challenge Scopes: repo
    • body: Review comment text (string, optional)
    • commitID: SHA of commit to review (string, optional)
    • event: Review action to perform. (string, optional)
    • method: The write operation to perform on pull request review. (string, required)
    • owner: Repository owner (string, required)
    • pullNumber: Pull request number (number, required)
    • repo: Repository name (string, required)
    • resolutionReason: Optional reason for resolving a Copilot code review thread: addressed, wont-fix, or invalid. (string, optional)
    • threadId: The node ID of the review thread (e.g., PRRT_kwDOxxx). Required for resolve_thread and unresolve_thread methods. Get thread IDs from pull_request_read with method get_review_comments. (string, optional)
<!-- END AUTOMATED FEATURE FLAG TOOLS -->