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. This INVALID_REQUEST error wraps the JSON unmarshal failure, meaning the body of an initialize request is malformed or does not match the MCP initialize schema (missing/incorrectly typed protocolVersion, capabilities, clientInfo).

Source

Thrown at internal/server/mcp/v20250326/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. Send a valid JSON body matching the MCP InitializeRequest schema: {protocolVersion, capabilities, clientInfo}
2. Validate the payload with a JSON linter or MCP schema before sending
3. Check that Content-Type and encoding are correct and the body isn't truncated
4. Update the client SDK to a version compatible with the 2025-03-26 schema

Example fix

// before
{"protocolVersion":"2025-03-26","capabilities":"all"}
// after
{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}

const body = JSON.parse(raw)
if (typeof body.protocolVersion !== "string" ||
    typeof body.capabilities !== "object" ||
    typeof body.clientInfo?.name !== "string") {
  throw new Error("malformed initialize request")
}

function isInitializeRequest(b: unknown): b is InitializeRequest {
  const r = b as InitializeRequest
  return typeof r === "object" && r !== null &&
    typeof r.protocolVersion === "string" &&
    typeof r.capabilities === "object" &&
    typeof r.clientInfo === "object"
}

try {
  const res = await client.initialize(req)
} catch (e) {
  if (e.code === -32600) { // INVALID_REQUEST
    console.error("initialize body rejected:", e.message, JSON.stringify(req))
  }
  throw e
}

When it happens

Trigger: json.Unmarshal(body, &req) fails in initializeHandler because the body is not valid JSON or the fields don't match InitializeRequest's types.

Common situations: Hand-rolled MCP clients sending wrong field types (e.g. capabilities as a string); empty bodies; clients built against a divergent MCP schema; proxies mangling the payload.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• INVALID_REQUEST
• INVALID_REQUEST
• INVALID_REQUEST
• failed to decode Google tokeninfo response: %w
• invalid notification request: %w

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