github/github-mcp-server · error · ErrUnknownTools

unknown tools specified in WithTools: %s

Error message

unknown tools specified in WithTools: %s

What it means

inventory.Builder.Build() validates every tool name passed via WithTools against the registered catalog (validToolNames). Names that are neither registered tools nor entries in the deprecatedAliases map are collected and returned in one error wrapping the ErrUnknownTools sentinel, comma-joined. Known deprecated aliases are transparently remapped to their canonical tool, so only truly unknown names reach this error.

Source

Thrown at pkg/inventory/builder.go:267

		var unrecognizedTools []string
		for _, name := range cleanedTools {
			// Always include the original name - this handles the case where
			// the tool exists but is controlled by a feature flag that's OFF.
			r.additionalTools[name] = true
			// Also include the canonical name if this is a deprecated alias.
			// This handles the case where the feature flag is ON and only
			// the new consolidated tool is available.
			if canonical, isAlias := b.deprecatedAliases[name]; isAlias {
				r.additionalTools[canonical] = true
			} else if !validToolNames[name] {
				// Not a valid tool and not a deprecated alias - track as unrecognized
				unrecognizedTools = append(unrecognizedTools, name)
			}
		}

		// Error out if there are unrecognized tools
		if len(unrecognizedTools) > 0 {
			return nil, fmt.Errorf("%w: %s", ErrUnknownTools, strings.Join(unrecognizedTools, ", "))
		}
	}

	if b.generateInstructions {
		r.instructions = generateInstructions(r)
	}

	return r, nil
}

// processToolsets processes the toolsetIDs configuration and returns:
// - enabledToolsets map (nil means all enabled)
// - unrecognizedToolsets list for warnings
// - allToolsetIDs sorted list of all toolset IDs
// - toolsetIDSet map for O(1) HasToolset lookup
// - defaultToolsetIDs sorted list of default toolset IDs
// - toolsetDescriptions map of toolset ID to description
func (b *Builder) processToolsets() (map[ToolsetID]bool, []string, []ToolsetID, map[ToolsetID]bool, []ToolsetID, map[ToolsetID]string) {

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Diff your tool list against the deployed server's tools/list response - the exact registered names appear there
2. Check the deprecatedAliases map in pkg/inventory/builder.go and pkg/toolsets registrations for renames; switch to the canonical name
3. Align the allowlist with the server version you actually deploy (pin the version)
4. For renamed tools use the new canonical name - only aliases registered in deprecatedAliases are auto-mapped

Example fix

// before
inv, err := inventory.NewBuilder().
	SetTools(...).
	WithTools([]string{"search_reopsitories"}).Build()

// after
inv, err := inventory.NewBuilder().
	SetTools(...).
	WithTools([]string{"search_repositories"}).Build()

// seed the allowed set from the same registry the builder uses
valid := map[string]bool{}
for _, name := range registeredToolNames(t, hostType) { // from github.AllTools(...)
	valid[name] = true
}
for _, name := range wantedTools {
	if !valid[name] {
		return fmt.Errorf("tool %q is not registered in this server version/host", name)
	}
}

func isUnknownTools(err error) bool { return errors.Is(err, inventory.ErrUnknownTools) }

if _, err := b.Build(); err != nil {
	if errors.Is(err, inventory.ErrUnknownTools) {
		// the comma-separated names after the colon are exactly the bad entries - fix each
	}
	return err
}

When it happens

Trigger: Calling WithTools with a typo ('search_reopsitories'), a name that was renamed without a registered alias, or a name from a newer release's docs used against an older binary.

Common situations: Tool allowlists in config/env written against a different server version; copy-paste of tool IDs whose names include a suffix people drop; host-type-specific tools requested on a host that does not offer them.

Related errors

• unknown tools specified in WithTools
• failed to build inventory for tool scope map: %w
• could not parse host as URL: %s
• GitHub App authentication and OAuth login (--oauth-client-id
• GitHub App installation ID is required (GITHUB_APP_INSTALLAT

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