github/github-mcp-server · error

unknown tools specified in WithTools

Error message

unknown tools specified in WithTools

What it means

ErrUnknownTools is returned by inventory.Builder.Build() when one or more tool names passed to WithTools() are neither registered tool names nor deprecated aliases. Build validates every cleaned name against the set of registered tools (plus the deprecated-alias map) and fails hard, listing the offending names in the wrapped message. It signals a configuration mistake: a typo, a removed tool, or a name that only exists in another build/feature set.

Source

Thrown at pkg/inventory/builder.go:14

package inventory

import (
	"context"
	"errors"
	"fmt"
	"maps"
	"slices"
	"strings"
)

var (
	// ErrUnknownTools is returned when tools specified via WithTools() are not recognized.
	ErrUnknownTools = errors.New("unknown tools specified in WithTools")
)

// mcpAppsFeatureFlag is the feature flag name that controls MCP Apps UI metadata.
// This is defined here to avoid importing pkg/github (which imports pkg/inventory).
// The value must match github.MCPAppsFeatureFlag.
const mcpAppsFeatureFlag = "remote_mcp_ui_apps"

// ToolFilter is a function that determines if a tool should be included.
// Returns true if the tool should be included, false to exclude it.
type ToolFilter func(ctx context.Context, tool *ServerTool) (bool, error)

// Builder builds a Registry with the specified configuration.
// Use NewBuilder to create a builder, chain configuration methods,
// then call Build() to create the final inventory.
//
// Example:
//
//	reg := NewBuilder().

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Read the wrapped message: it lists the exact unrecognized names
2. Check canonical tool names via the repo docs (docs/feature-flags.md, docs/tool-renaming.md) or by listing tools from a working build
3. Fix typos and replace removed names with their current equivalents (deprecated aliases are auto-resolved, so use the newest name)
4. If embedding the builder, validate names against your registered ServerTool set before calling WithTools

Example fix

// before
inv, err := github.NewInventory(t).WithTools([]string{"create_issue", "add_issue_comment"}).Build()

// after (names renamed in this version)
inv, err := github.NewInventory(t).WithTools([]string{"issue", "issue_comment"}).Build()

// Before WithTools, diff requested names against the registry's tools
registry := inventory.NewRegistry() // your populated registry/ServerTool source
valid := map[string]bool{}
for _, t := range registry.Tools() {
    valid[t.Tool.Name] = true
}
for _, name := range requestedTools {
    if !valid[name] {
        return fmt.Errorf("unknown tool %q; check canonical names in docs", name)
    }
}
inv, err := inventory.NewBuilder().SetTools(registry.Tools()).WithTools(requestedTools).Build()

// Detect the sentinel in returned errors
func isUnknownTools(err error) bool {
    return err != nil && errors.Is(err, inventory.ErrUnknownTools)
}

inv, err := builder.WithTools(names).Build()
if err != nil {
    if errors.Is(err, inventory.ErrUnknownTools) {
        // config problem: log the listed names and fail fast with a clear message
        log.Fatalf("invalid tools config: %v", err)
    }
    return err // unexpected builder failure
}

When it happens

Trigger: Calling WithTools([]string{"create_issue"}) when the registered name is 'create_issue' vs 'issue' style renames; a typo like 'get_pull_requests' vs the actual registered name; a tool removed in the current version; a name that is a toolset name rather than a tool name. Build() then returns fmt.Errorf("%w: %s", ErrUnknownTools, names...).

Common situations: Upgrading github-mcp-server after tool renames/consolidation and keeping old names in --tools config; mixing up toolset names ('issues', 'repos') with tool names; feature-flag-gated names are NOT a trigger (aliases and flagged tools are pre-resolved); copy-paste from outdated docs.

Related errors

• failed to build inventory: %w
• unknown tools specified in WithTools: %s
• creating installation token request: %w
• failed to create observability exporters: %w
• failed to build inventory for tool scope map: %w

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/c2873488e267957d. Report an issue: GitHub.