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 the body is not valid JSON or lacks the expected shape, it wraps the unmarshal error as "invalid mcp initialize request: %w" and returns JSON-RPC INVALID_REQUEST. It fires during the MCP initialization handshake.

Source

Thrown at internal/server/mcp/v20241105/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. Read the wrapped cause in the message to see which JSON field failed to decode.
2. Ensure the body is valid JSON matching InitializeRequest: {"jsonrpc":"2.0","id":...,"method":"initialize","params":{"protocolVersion":"...","capabilities":{},"clientInfo":{"name":"...","version":"..."}}}.
3. Send with Content-Type: application/json to the correct MCP endpoint path.
4. Use an official MCP client SDK to construct the initialize request instead of hand-writing it.

Example fix

// before: missing params -> unmarshal failure
{"jsonrpc":"2.0","id":1,"method":"initialize"}
// after: complete initialize request
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}

// Validate the initialize payload before sending
function buildInitializeRequest(id, version) {
  const params = {
    protocolVersion: version,
    capabilities: {},
    clientInfo: { name: "my-client", version: "1.0.0" }
  };
  const body = JSON.stringify({ jsonrpc: "2.0", id, method: "initialize", params });
  JSON.parse(body); // throw early on serialization bugs
  return body;
}

function isInitializeRequest(r) {
  return r.jsonrpc === "2.0" && r.method === "initialize" &&
    typeof r.params?.protocolVersion === "string" &&
    typeof r.params?.clientInfo?.name === "string";
}

if (res.error && res.error.code === -32600 && /invalid mcp initialize request/.test(res.error.message)) {
  console.error("Initialize body rejected:", res.error.message); // cause is embedded
}

When it happens

Trigger: POSTing an initialize request whose body is malformed JSON, empty, or missing required fields (protocolVersion/capabilities/clientInfo shape mismatch) to the MCP endpoint.

Common situations: Hand-crafted curl tests with quoting/escaping errors; clients sending initialize with wrong field names or nesting; proxies or gateways altering the body; sending the initialize payload to the wrong endpoint or with the wrong content type.

Related errors

• invalid notification request: %w
• INVALID_REQUEST
• INVALID_REQUEST
• INVALID_REQUEST
• Mcp-Method header value '%s' does not match body value '%s'

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