googleapis/mcp-toolbox · error

INVALID_REQUEST

INVALID_REQUEST

Error message

invalid mcp initialize request: %w

What it means

initializeHandler unmarshals the request body into InitializeRequest; if JSON unmarshaling fails this INVALID_REQUEST error is returned. The body was not a valid JSON object matching the MCP initialize request shape.

Source

Thrown at internal/server/mcp/v20251125/method.go:73

		return promptsGetHandler(ctx, id, g, primitiveMgr, body)
	default:
		err := fmt.Errorf("invalid method %s", method)
		return jsonrpc.NewError(id, jsonrpc.METHOD_NOT_FOUND, err.Error(), nil), err
	}
}

// InitializeResponse runs capability negotiation and protocol version agreement.
// This is the Initialization phase of the lifecycle for MCP client-server connections.
// Always start with the latest protocol version supported.
func initializeHandler(ctx context.Context, id jsonrpc.RequestId, body []byte) (any, error) {
	v, err := util.ToolboxVersionFromContext(ctx)
	if err != nil {
		return jsonrpc.NewError(id, jsonrpc.INTERNAL_ERROR, err.Error(), nil), err
	}

	var req InitializeRequest
	if err := json.Unmarshal(body, &req); err != nil {
		err = fmt.Errorf("invalid mcp initialize request: %w", err)
		return jsonrpc.NewError(id, jsonrpc.INVALID_REQUEST, err.Error(), nil), err
	}

	toolsListChanged := false
	promptsListChanged := false
	result := InitializeResult{
		ProtocolVersion: PROTOCOL_VERSION,
		Capabilities: ServerCapabilities{
			Tools: &ListChanged{
				ListChanged: &toolsListChanged,
			},
			Prompts: &ListChanged{
				ListChanged: &promptsListChanged,
			},
		},
		ServerInfo: Implementation{
			BaseMetadata: BaseMetadata{
				Name: SERVER_NAME,

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Validate the request body is complete JSON matching InitializeRequest: protocolVersion, capabilities, clientInfo (name/version).
2. Inspect the wrapped cause in the error message to identify the exact unmarshal failure (missing field or type mismatch).
3. Ensure the HTTP request Content-Type is application/json and the body is sent correctly by the transport.
4. Use an official MCP client/SDK to generate the initialize request rather than hand-crafting it.

Example fix

// before: missing clientInfo
{"protocolVersion":"2025-11-25","capabilities":{}}
// after
{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}

function isValidInitializeBody(body) {
  return typeof body === 'object' && body !== null &&
    typeof body.protocolVersion === 'string' &&
    typeof body.capabilities === 'object' && body.capabilities !== null &&
    typeof body.clientInfo === 'object' && body.clientInfo !== null &&
    typeof body.clientInfo.name === 'string' &&
    typeof body.clientInfo.version === 'string';
}

function isInitializeRequest(v) {
  return typeof v === 'object' && v !== null && 'protocolVersion' in v && 'capabilities' in v && 'clientInfo' in v;
}

try {
  const res = await rpc.call('initialize', initParams);
} catch (e) {
  if (e.code === -32600 && /invalid mcp initialize request/.test(e.message)) {
    // fix payload shape and retry once
  } else throw e;
}

When it happens

Trigger: tools/initialize requests whose body is malformed JSON, lacks required fields (protocolVersion, capabilities, clientInfo), or has wrong field types (e.g. clientInfo as a string instead of an object).

Common situations: Hand-rolled MCP clients sending incomplete initialize payloads; transport corruption or empty bodies; sending query parameters but no JSON body; using a pre-initialization schema from an older spec draft.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• INVALID_REQUEST
• INVALID_REQUEST
• INVALID_REQUEST
• description is required for tool %q
• HTTP error! status: ${response.status}

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