Skip to content

Add opt-in GraphQL query and mutation tools - #3877

Open
gwomtt wants to merge 2 commits into
github:mainfrom
team-table:opt-in-graphql
Open

gwomtt wants to merge 2 commits into
github:mainfrom
team-table:opt-in-graphql

Conversation

@gwomtt

@gwomtt gwomtt commented Nov 17, 2026 •

Copy link
Copy Markdown

Closes #2437.

Earlier work: #645 proposed a CLI-like GraphQL toolset and closed without merging.

We use a remote OAuth connector so a cloud agent can manage tickets from a phone while the user’s computer is offline. For example, it can use GitHub’s API to set a native “Relates to” relationship between issues and verify it, or update an organisation Project field. When GitHub ships a new API capability, agents can already use it through the CLI, but MCP clients need a dedicated tool or another integration. Direct GraphQL would let those clients use the same GitHub credential to read or change issues and projects.

This adds a server-side opt-in and a separate GraphQL toolset. Query and mutation are separate tools so clients can distinguish reads from writes. The server selects a fixed operation name and type. Read-only mode filters out the mutation tool. Both handlers decline to execute with lockdown or IFC labels enabled. Deployments that depend on a narrowly scoped tool list can leave the feature disabled.

The branch includes operation-selection and registration tests and documents the input format. We verified authenticated GraphQL reads and a ref creation through a self-hosted deployment of the feature. No hosting or container defaults are changed by this PR.

The existing form-deferral setting is independent of this feature. No bundled skill requires the new optional tools.

@gwomtt
gwomtt requested a review from a team as a code owner November 17, 2026 22:39
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 22:39

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The GraphQL tools bypass typed output registration and fail enabled-configuration checks, while also omitting response sanitization and shared GitHub error handling.

6 open issues
What changed in this PR

Adds opt-in GraphQL access to the GitHub MCP Server so clients can use GitHub API capabilities without waiting for dedicated MCP tools.

Changes:

  • Introduces a server-gated graphql toolset with separate query and mutation tools using the current request’s credentials.
  • Sets operation type and name server-side, supports read-only filtering, and blocks execution under lockdown or IFC labels.
  • Adds payload and registration tests, plus documentation for enabling and calling the tools.
File Description
pkg/​github/​tools.go Registers GraphQL tools only when the environment opt-in is enabled.
pkg/​github/​graphql_operation.go Defines tool schemas, operation payloads, request handling, and execution guards.
pkg/​github/​graphql_operation_test.go Tests operation construction and tool registration.
docs/​streamable-http.md Documents configuration, access implications, restrictions, and input format.

Review effort: Max (adaptive)

Comment thread pkg/github/graphql_operation.go Outdated
var graphqlToolset = inventory.ToolsetMetadata{
ID: "graphql",
Description: "Execute operations against the GitHub GraphQL API",
Icon: "code",
}
}

func graphqlOperationTool(write bool) inventory.ServerTool {
Comment thread pkg/github/graphql_operation.go Outdated
Description: description,
InputSchema: contextToolInputSchema[graphqlOperationInput](nil),
Annotations: &mcp.ToolAnnotations{ReadOnlyHint: !write, DestructiveHint: ToBoolPtr(write)},
}, scopes.NoScopes(), func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, input graphqlOperationInput) (*mcp.CallToolResult, any, error) {
Comment thread pkg/github/graphql_operation.go Outdated
Comment on lines +79 to +80
if _, err := client.Do(req, &response); err != nil {
return utils.NewToolResultErrorFromErr("GitHub GraphQL request failed", err), nil, nil
if _, err := client.Do(req, &response); err != nil {
return utils.NewToolResultErrorFromErr("GitHub GraphQL request failed", err), nil, nil
}
result := MarshalledTextResult(response)
Comment thread pkg/github/tools.go Outdated
Comment on lines +420 to +421
if os.Getenv("GITHUB_MCP_ENABLE_GRAPHQL") == "true" {
tools = append(tools, graphqlOperationTool(false), graphqlOperationTool(true))
@gwomtt

gwomtt commented Nov 18, 2026

Copy link
Copy Markdown
Author

Addressed the six review points in 0abff7d. The tools now use the embedded code-square icon, exported constructors and a concrete response envelope. HTTP failures use the shared GitHub error handler. Nested response strings are sanitised in both data and errors, and the decoder preserves JSON numbers. The catalog test exercises the operator-enabled toolset with explicit exemptions.

Verified go test -short ./... and reran the GraphQL registration, concrete output and catalog coverage tests with GITHUB_MCP_ENABLE_GRAPHQL=true. Both runs passed.

@gwomtt

gwomtt commented Nov 18, 2026

Copy link
Copy Markdown
Author

Could a maintainer re-request Copilot review on 0abff7d when convenient? Its review was on 5099429, and my contributor account can’t request reviewers on this repository through the API. The six fixes and passing test runs are summarised in the follow-up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for raw GraphQL queries

2 participants