googleapis/mcp-toolbox · error

invalid source for %q tool: source %q is not a compatible ty

Error message

invalid source for %q tool: source %q is not a compatible type

What it means

This error is thrown by the cloudhealthcare-fhir-patient-everything tool's ValidateSource when the sources.Source passed to the tool does not implement the tool's compatibleSource interface (the Cloud Healthcare source methods the tool needs, such as FHIR store accessors and UseClientAuthorization). MCP Toolbox wires tools to sources by name in the YAML config; this guard ensures at runtime that the bound source actually provides the API surface the tool requires. It is a programming/config error, not a transient failure.

Source

Thrown at internal/tools/cloudhealthcare/cloudhealthcarefhirpatienteverything/cloudhealthcarefhirpatienteverything.go:107

// validate interface
var _ tools.Tool = Tool{}

type Tool struct {
	tools.BaseTool[Config]
}

func (t Tool) GetSourceName() string {
	return t.Cfg.Source
}

func (t Tool) ToConfig() tools.ToolConfig {
	return t.Cfg
}

func (t Tool) ValidateSource(source sources.Source) error {
	_, ok := source.(compatibleSource)
	if !ok {
		return fmt.Errorf("invalid source for %q tool: source %q is not a compatible type", t.Cfg.Type, t.Cfg.Source)
	}
	return nil
}

func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) {
	source, ok := s.(compatibleSource)
	if !ok {
		return nil, util.NewClientServerError("source used is not compatible with the tool", http.StatusInternalServerError, nil)
	}
	storeID, err := common.ValidateAndFetchStoreID(params, source.AllowedFHIRStores())
	if err != nil {
		// ValidateAndFetchStoreID usually returns input validation errors
		return nil, util.NewAgentError("failed to validate store ID", err)
	}
	patientID, ok := params.AsMap()[patientIDKey].(string)
	if !ok {
		return nil, util.NewAgentError(fmt.Sprintf("invalid or missing '%s' parameter; expected a string", patientIDKey), nil)
	}

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Set the tool's source in tools.yaml to a source whose kind is cloudhealthcare (see internal/sources/cloudhealthcare/cloud_healthcare.go).
  2. Verify the source name referenced by the tool matches the declared source key (check for typos/yaml indentation).
  3. If using a custom or mock source, implement all methods of the tool's compatibleSource interface (FHIR store accessors and UseClientAuthorization() bool).
  4. Rebuild after any source refactor so the registered source is the concrete cloudhealthcare Source type.

Example fix

# before (tools.yaml)
tools:
  fhir-patient-everything:
    kind: cloudhealthcare-fhir-patient-everything
    source: my-postgres

# after
tools:
  fhir-patient-everything:
    kind: cloudhealthcare-fhir-patient-everything
    source: my-healthcare  # a source declared with kind: cloudhealthcare
Defensive patterns

Strategy: type-guard

Validate before calling

// Before initializing the toolbox, parse your tools.yaml and check bindings:
// every tool of kind cloudhealthcare-* must reference a source with kind: cloudhealthcare.
func sourceIsCompatible(s sources.Source) bool {
	_, ok := s.(interface {
		UseClientAuthorization() bool
		GetFHIRStore(string) (*healthcare.FHIRStore, error)
	})
	return ok
}

Type guard

func asCompatibleSource(s sources.Source) (compatibleSource, bool) {
	cs, ok := s.(compatibleSource)
	return cs, ok
}

Try / catch

if err := tool.ValidateSource(src); err != nil {
	// invalid-source errors are configuration bugs; do not retry.
	log.Fatalf("tool/source binding invalid: %v", err)
}

Prevention

When it happens

Trigger: Calling ValidateSource (directly or via server/tool initialization when a tool is bound to a source) with a sources.Source whose concrete type is not the cloudhealthcare source — e.g. a postgres, http, or storage source, or a hand-rolled Source implementation — so the type assertion source.(compatibleSource) fails.

Common situations: The tools.yaml binds the cloudhealthcare-fhir-patient-everything tool to a source declared with a different kind (e.g. kind: postgres instead of kind: cloudhealthcare); a typo in the source name resolves to the wrong source; a custom test double for the source does not implement every compatibleSource method; a refactor renames/moves the Source type so it no longer satisfies the interface.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/a9365c2b6341021e. Report an issue: GitHub.